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The AdvaBuild Object Type Builder package is an option for the Advant Station 500 Series 
Information Management Station (IMS). To use AdvaBuild Object Type Builder, AdvaInform 
Basic Unit software must be installed. 


This book describes the AdvaInform Object Type Builder for both Advant OCS with Master 
software and with MOD 300 software. There are some differences in Object Type Builder 
between Master and MOD 300. These are mainly related to differences in object types between 
the two systems and the support for event and alarm distribution. Wherever such differences 
occur in the book they will be marked with a parenthesis (Master) or (MOD 300). A detailed 
description of the differences is given in Section 1.4, How to Use This Book. 


Object Type Builder is the most powerful IMS tool for development of applications. It makes it 
possible to integrate ABB, third-party or end user applications with the Advant OCS in an 
effective way. The resulting User Objects provide a high performance solution to the application 
needs. They are also fully integrated with the rest of the Advant OCS with automatic support for 
distribution, event and alarm! handling, dialogs etc. At the same time you are relieved from a lot 
of the programming as Object Type Builder takes care of all: 


° core system interaction to handle the 
— reading of input data from other objects (such as process and user objects) 
— sending of operations to other objects 
— raising of events (for other objects waiting to be notified about an occurrence) 


— sending of event and alarm! messages to the event and alarm system. A result from a 
third party package can be used in a User Object to generate events/alarms! to notify 
an operator. 


° server support. This means that any other object can read the attributes of a User Object 
and no programming at all is needed. It also means that all operation requests that a User 
Object receives are automatically handed over to the operations that you have written for 
the object type. 


° creation of the Object Type information (executable and database information) that is 
required to export the object types to AdvaInform Object Handling for instance creation 
and execution. 


° design and creation of the database tables that the user object type instances will be 
stored in. 


This reduces the time you spend in training and enables you to work at a higher level of 
abstraction. It also reduces the development time by making it possible to re-use User Objects as 
solutions to frequently occurring applications. 


You can also combine the strength of Object Type Builder with the AdvaInform User API. The 
User API library routines can be called from User Objects. This brings additional flexibility to 
the User Object concept such as access to History logs. 


1. See Section 1.4.1, Differences Between Master and MOD 300 
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Finally, the power of good examples is exemplified by all the examples included in Object Type 
Builder. Examples close to your own needs can be found and development can be started with 
much shorter training and preparation time. For example, the complete source code on how to 
use the User API library to access Historical data is provided. 


This manual is intended for developers, project engineers, and programmers building 
applications with Object Type Builder. It allows you to describe and implement applications as 
one or several User Object Types. 


User Objects are portable between all Advant Stations configured for IMS applications. 
Functions needed when the resulting objects are configured and executed in IMS are provided 
by the AdvaInform Object Handling option. See the Advalnform Object Handling User’s Guide 
for further information. 


1.2 Equipment Requirements 


1.3 Conventions 


Object Type Builder is an IMS option designed to run in conjunction with the AdvaInform 
Basic Unit. It runs on all Advant Station 500 Series IMS workstations. 


The following typographic conventions are used in this document: 


° The names of keyboard keys, push buttons, menus, and menu items are boldfaced. System 
prompts/messages are in the Courier font, and user responses/input are bold. 


° The names of referenced manuals are italics. 


1.4 How to Use This Book 


1-2 


MOD 300 and Master 
This guide covers both MOD and Master. This is handled in two ways: 


° In some cases when the operation/commands differs two alternatives are described - one 
for MOD and one for master 


° When the difference is restricted to for example object type only, the MOD alternative is 
described in brackets: ... (MOD: xxxxxxx). 
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As previously described, this book covers the AdvaInform Object Handling both for Master and 
MOD 300. The differences for Object Handling in the two systems are as follows: 


The Basic Objects differ: 


° In a Master system, the process object types AI,AO, DI, DO, DAT and TEXT also exist in 
the controllers. The operator station has object displays and display elements for them. 
These object types exist in Object handling in MOD 300 as well; however, they are less 
useful due to the limited support by the rest of the system. 


° The MOD 300 process objects DATA_FCM and VA_STRING_FCM also exist in the 
controllers and are supported by the operator stations. 


These process types exist in Master as well; however, they are less useful due to the 
limited support by the rest of the system. 


° The coRTM usage in the MOD 300 system is limited. 


The event and alarm handling differs. In Master, events, alarms and alarm acknowledge is 
supported. In MOD 300, TCL Billboard Messages can be created. In Master the messages are 
also stored locally which is not the case for MOD 300. 


To avoid lengthy explanations at each instance, the term event and alarm messages is used 
throughout the document even though only part of the functionality is applicable for MOD 300. 
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1.4.2 Documentation Structure 


Figure 1-1 shows the basic structure of Advant documentation. Each document, describing 
hardware or software, is built around this structure so you can easily locate information in any 
of the documents. Sections that contain no information are labeled Not applicable. 


~ 


Configuration/ 


Introduction Installation | | App! ae eet Maintenance | | Appendices Index 
Before You Site Planning Design Operating Preventive Appendix A 
Begin Environment Considerations Overview Maintenance Syntax Descr. 

OTDL 
Equipment Setu Capacity & Product Hardware : 
Requirements , Porformanes Operation Indicators Appendix B 
Shut-down Object Builder 
moe - ae” Procedures Soe a rat Commands 
is Boo etu utoria essages : 
Start-u p 9 Appendix C 
Conventions Procedures _ Tutorial Operating Fault Finding Object Parser 
aie —_ Maple Instructions & User Repair Commands 

elate roduct pplication i 

Documentation Verification Procedures Runtime Oper Ul 2 
. Operation C d 
Release Accessing Menus ome 
History UserAPI Appendix E 
functions Object Handler 
Terminology : Commands 
Menus Section 

Product Appendix F 

Overview Object Type 

User Interface Eros 
Appendix G 
External 


Figure 1-1. Basic Documentation Structure 


Chapter 1, Introduction 


Communication 
Library 


Appendix H 
Event Handling 
Constants 


Appendix | 
Debugging of User 
Object Applications 


Provides you with basic information about Object Type Builder. 


Chapter 2, Installation 


For step-by-step instructions on how to install Object Type Builder software. 
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Chapter 3, Configuration and Application Building 


Describes how to use the Object Type Builder. The chapter includes a tutorial which describes 
the development of typical User Objects. Section 3.5, Application Procedures, provides you 
with guidelines on how to design your application using User Objects. The programming of 
User Objects is described in detail. The remainder of the chapter consists of an overview of the 
Object Type Builder tools. 


Chapter 4, Operation 


Provides you with information on how to operate the Object Type Builder’s facilities. 


Chapter 5, Maintenance 


If you run into problems and need help or encounter errors using Object Type Builder. 


Reference Material 

° Appendix A, Syntax Description OTDL 

° Appendix B, ObjectBuilder Commands 

° Appendix C, ObjectParser Commands 

° Appendix D, ObjectUtil Commands 

° Appendix E, Object Handlers Commands, and 


° Appendix F, Object Type Examples provide detailed information about Object Type 
Builder’s usage and the User Object programming. You will find syntax requirements, 
command syntax and more. 


° Appendix G, External Communication Library contains some complete User Object 
examples. 


° Appendix H, Event Handling Constants contains a table with event reasons and a list of 
event properties. 


° Appendix I, Debugging of User Object Applications shows how to debug your objects. 
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1.5 Related Documentation 


The documentation related to this manual is shown in Table 1-1. 


Table 1-1. Related Documentation 


Category 


Title 


Description 


Hardware 


Advant Station 5xxHardware User’s Guide 


This book covers the installation and 
maintenance of the hardware for an Advant 
Station. 


Station 


Advant Station 500 Series IMS User’s Guide 


This book provides instructions for system 
administration functions such as backup and 
restore. 


Software 


Advalnform Basic Functions User’s Guide 


This book describes the basic functions that 
support all Advalnform software packages. 


Options 


Advalnform History User’s Guide 


This book describes, for example, how to 
configure the History Logs that log User Object 
attributes. 


Options 


Advalnform Object Handling User’s Guide 


The configuration and execution environment 
for User Objects. You must have an Object 
Handling option to execute your objects. 


Other 


Advalnform User API User’s Guide 


Describes the User API libraries and provides 
examples how to use them. 


Other 


Advalnform Object Types Reference Manual 


This book provides table names and attribute 
names for all object types supported by IMS. 


1.6 Release History 
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Table 1-2. Release History 


with IMS 


Version Description 
1.0 Initial release of the AdvaBuild Object Type Builder for the Advant 
Station 500 series. 
1.1 « The EC library which lets you integrate foreign vendor systems 


New functionality through the utility ObjectUtil: 


ability to activate and deactivate database shadowing, see, 
Appendix D, ObjectUtil Commands and Section 1.8.4.8, Object 


ability to dump instances into text file and load them into 
another IMS system using that text file. 
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Table 1-2. Release History (Continued) 


1.2 


Improved dump and load of objects instances to and from text files 


The ability to balance the load User Objects apply on the 
controllers. 


Synchronous output as well as buffered asynchronous output from 
User Objects. Synchronous handling of commands allows for 
return of parameters from given commands, buffered 
asynchronous output improves performance as all output 
commands are sent together. 


Support for a more sophisticated event triggering functionality. 
3 new basic objects: 


— Run Time Measurement - Measures the time Your devices run 
and the number of starts and stops. Generates event 
messages to Operator Stations when run time limits are 
exceeded. 


— Basic Calculation - Calculates sum, average and a number of 
other mathematical algorithms from 2 to 10 inputs. The result is 
evaluated towards alarm limits. Data storage, alarm handling 
and presentation is done in Al object attributes. 


— Executor - You can configure this object to execute any third 
party or application software of your own choice. 


Support for debug of objects. 
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Table 1-2. Release History (Continued) 


Support to call UserAPI functions from UserObject application 
code. Example programs are included. 


New functionality accessible from operation code 


— When an object is configured to execute in cyclic intervals, the 
interval can be read from the new operation getCycliclnterval(). 
The interval can be modified from the operation code by the 
new operation setCyclicinterval(). 


— The Oracle shadowing can be turned on/off from the operation 
code. It is also possible to call a function which stores and 
commits the attribute values to Oracle. 


— A function which deactivates the object, is made available. 
Support to specify the linking order of external libraries. 
Support to define environment variables for an object handler. 


Support to define an operation which is executed when an object 
is deactivated.§ 


Support for TCL Billboard messages in a MOD 300 systems. 


Supports HP-UX 10.20. 
All basic objects are available both in Master and MOD 300. 
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1.7 Terminology 


1.7.1 Acronyms 
The following acronyms are used in this document: 
IMS Information Management Station 
Os Operator Station 
OTD Object Type Definition. 


OTDL Object Type Definition Language. The name of the definition language that is used to 
describe object types. 


EC External Communication. 


1.7.2 User Object terminology 


Advant technology is based on client-server and object oriented technology. This makes it 
possible to distribute the AdvaBuild, AdvaInform and AdvaCommand functions into several 
products. 


The client-server concept as well as the data distribution is something you as a user can benefit 
from. Object Type Builder lets you build your applications utilizing this technology in a way 
that conforms to the AdvaInform and AdvaCommand functions. 


A typical application reads data from and stores data to other applications. It lets other 
applications read its public data and handles requests to perform certain operations. It can also 
produce events and alarms and send them to Event and Alarm subscribers. 


Data Requests 


The public data of the 
application is requested by 
operators and other applications 


Public Data 


one . Operation Requests 
Reading Application Code Begueete i a 
and writing (operations) fomoner 

data from / applications to 

to other ; execute operations 
applications Qperating 

(objects) ystem 


Events and Alarms/TCL Billboard Messages 
Messages are sent to the 

event and alarm system and 

to message logs 


Figure 1-2. A Typical Application 
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Using an object-oriented approach, you can describe any application as an object. Figure 1-3 
shows a typical application and how any application can be described as a User Object. 


Core System 


CONNECTIONS 
Subscriptions 
las 
Operation J\ Opera 
“ a 


and 
tion 
COMMANDS 
Z- aN 


Messages to the 
Event and Alarm 
subscribers 


SUBSCRIPTIONS 
On request and as 
a result of EVENTS 


COMMANDS 


Figure 1-3. Application Described as a User Object 


The application code is split into two parts: 


Normal Operation: The algorithm to combine input data (attributes and connections) to 
create output data. Normal Operation is executed when the object: 


— is started for the first time after a shutdown, 


is started by a cyclic schedule, 
— is started by an event, or 
— is given the command NormalOperation. 


Command Operation: The service to execute in response to a command. 


Three facilities available through the core system are used for the interaction between objects: 


Command: A function provided by the core system to request the execution of an object 
Operation. As a result, the object executes the corresponding Normal or Command 
Operation. 


Subscription: A function provided by the core system to read data (attributes). 

The request can ask for data to be returned immediately or when a specified Event occurs 
(to be triggered). Within the OTDL language the term subscription is used to describe 
composite attributes. 


Event: Events are defined with an event declaration. A User Object can declare an event 
that other objects e.g. User Objects subscribe on. When the event occurs, the subscriber is 
activated. You program the raising of events in the Normal and Command Operations. 
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Inputs and outputs are described with two terms, attribute and connection: 


Attribute: Describes the object’s public data. The application result is commonly stored in 
attributes, which also contain configured public information. Applications (other objects) 
can request the object’s public data through the core system using subscriptions or from 
the corresponding Oracle instance table using SQL!. This is completely transparent for the 
application part of the User Object, you do not need to take any actions for this to function. 


Connection: Describes connections to other objects. The data from the input connections 
(attributes) are automatically read (using subscriptions) each time an object instance is 
executed. Each output to another object through an output connection is requested in the 
User Object application code (Normal and Command Operations) and will result in the 
sending of a command to the other object. 


Finally, messages to the Event and Alarm System and the Message Log are supported. 


You request the sending of messages to the message log (provided that the AdvaInform History 
option is installed) and to Event and Alarm subscribers from the Normal and Command 
Operations. In a Master system you can generate both event and alarms, in a MOD 300 system 
you can generate TCL Billboard messages. 


Client - Server 


The terms Client and Server can be explained with the following examples related to User 
Objects: 


A Client uses subscriptions to read attributes from another object. That object acts as a 
Server when it returns the requested attribute information. 


A Client uses commands to requests for an operation to be executed by another object. 
That object acts as a Server when it executes the operation. 


There can be many Clients asking for services to be done by a Server. 


The Clients and the Server may be in the same or in different nodes. 


1. 


See Section 1.8.4.9, Instance Execution 
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1.7.3 Definition of Terms 


Basic Objects 


Configuration 
Core system 


Advalnform Basic 
Unit 


Advalnform Basic 
Function 
Advalnform 
database 

IMS Menu 


Object 


Process objects 


System objects 


User Object Type 


The Master process objects AI, DI, AO, DO, DAT and Text are 
implemented as User Objects in IMS and provided in AdvaInform 
Object Handling. 


The MOD 300 objects DATA_FCM and VA_STRING_FCM are 
implemented as User Objects and provided in Object Handling. 


Furthermore, three additional object types are provided: 


° A Run time measurement object that lets you measure the run 
time for your devices (pumps, motors etc.) (Master only) 


° A basic calculation object which provides calculations such as 
average and sum on 2 to 10 inputs and stores the results in an AI 
object attributes. 


° An executor object that executes any type of application in the 
HP-UX environment. 


Creation or modification of an instance of, for example, an object type. 


All nodes in the Advant OCS system are communicating with each 
other through the core system. The core system provides services for 
the system and user applications. Using these services, the applications 
can communicate with each other whether they reside in the same node 
or in different nodes of different types. 


The minimum software you can buy. Contains AdvaInform Basic 
Functions, User API and SQL Connect. 


The minimum software required for an IMS station. The various 
functions are described in the Advalnform Basic Functions User’s 
Guide. 


The AdvalInform database is based upon the relational database Oracle. 


The IMS entry menu. From this menu, all of the installed AdvaInform 
and AdvaBuild options can be selected. Using the IMS menu is 
described in detail in the Advalnform Basic Functions User’s Guide. 


Any entity in the Advant OCS system that represents a user-visible 
function or piece of equipment. An object is user-visible if it is 
configurable by the “user” of the products, and/or if it delivers global 
data or performs commands. Objects are split into Process objects and 
System objects. 


Entities representing control and supervision functions. For example, 
AI, AO, PIDCON and CCF_CONTIN_LOOP. 


Software, in the form of objects, utilizing process supervision and 
management programs (functions), i.e., system status objects. 


A description of a type of object built with the Object Type Builder. 
The User Object type has a framework described by the attributes, 
connections, commands and events and behaves as described by the 
operations. 
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1.8 Product Overview 


1.8.1 Object Type Builder and Object Handling 
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Advant OCS is an object oriented system. A large number of pre-defined objects exist in Advant 
OCS. They provide functionality for data collection, process control and supervision, system 
status, long term data storage etc. 


For you as a user of Advant OCS it is also important that the application specific problems can 
be solved. The most powerful concept that is provided for application development in IMS is the 
concept of User Objects. The functionality of User Objects is provided as two separate options: 
AdvaBuild Object Type Builder, from now Object Type Builder and AdvaInform Object 
Handling, from now Object Handling. The Object Type Builder and Object Handling provide a 
consistent, uniform and user friendly environment for development of standard and user-specific 
applications. 


° Object Type Builder 


Object Type Builder is the development environment. It is a complete environment for 
design and implementation of applications in the form of objects. The result of the 
development - in the form of Object Types - is exported to the Object Handling option. 
This means that many IMS systems with User Object can be served by one development 
machine containing Object Type Builder. See figure Figure 1-4. 


° Object Handling 


Object Handling provides the tools for configuration, execution and status monitoring of 
User Objects. There are a number of pre-defined User Objects, so called Basic Objects 
included in Object Handling. You execute these, together with the application specific 
User Objects built for the plant, with the help of Object Handling, see Figure 1-4. 


Tarrant INAC 
Tarrant INAC 


Development and Tarant INC 


Test IMS I s eceeeee ee ape Target IMS 
ai 


Object Type Builder >! Object Handling 
Object Handling 


ABB products 
delivered as 
User Object Types 


Figure 1-4. Usage of Object Type Builder and Object Handling 


Many of the ABB functions/products which are specific for a certain type of industry are 
provided as User Objects. The ABB industry specialists have used Object Type Builder to 
develop the solutions. You can install and execute them through the usage of the option Object 
Handling. Examples on such applications developed or suitable to develop as User Objects are 
component lifetime calculations, run time measurement and various types of optimizations 
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1.8.2 Integration into the Advant OCS 


When your User Object types are finished and installed, you can create and execute instances 
which are completely integrated into the Advant OCS. The User Objects serve both as clients 
and servers, see Figure 1-5. 


TCP/IP 


Gperatar PCIs 


IMS 


"| 
ff 


Connect -AdvalInform 
Server Display 
-SQL client 


External DB 
via SQL*NET 


Controllers 


Figure 1-5. User Objects serve both as clients and servers 


The User Object can read data as a client from: 


Objects in Controllers 
User Objects in IMS stations 
Any data available through third party software. 


It can, utilizing commands, send data as a client to: 


Other User Objects 
Objects in Controllers 


Operator Stations (events and alarms) and Message Logs (provided the AdvaInform 
History option is installed) 


Third party software. 


It can also function as a data and command server towards other functions: 


Other User Objects 

AdvaInform History, AdvaInform Reports, AdvaInform Calculations (Master only) 
Operator Stations (Master only) 

AdvalInform Display displays 

User API applications 


3BSE 001 012R0501 


AdvaBuild® Object Type Builder User’s Guide 
Section 1.8.3 Development of User Objects 


° SQL Clients, for example a PC, can read the attribute data from the Oracle table of each 
object type. See Section 1.8.4.9, Instance Execution. 


° SQL*Connect Server Objects 


The data and command server functions are completely transparent for the application code 
within the User Object. 


1.8.3 Development of User Objects 
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Object Type Builder and Object Handling are separate, but closely related, options. Figure 1-6 
illustrates the relationship between Object Type Builder and Object Handling. 


All applications (objects) must be connected to one another through the core system to achieve 
fully integrated functionality. The core system provides communication functions used by all 
applications such as Subscriptions and Commands. It also connects all types of stations in the 
Advant OCS to each other. 


The core system is object-oriented— all applications must be described as object types. 

(See Section 1.8.4.2, Object Type Information, for further details.) Object Type Builder enables 
you to describe all applications, and their input and output, to the core system as object types so 
that all applications (system or customer) can share information about the process being 
controlled and about each other. 


AdvaBuild Process . 
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(2) Type 
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Implement 
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Figure 1-6. Steps in Application Development 
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Application development consists of three phases, and each phase consists of a number of 
actions (steps). 


Phase 1 of Application Development 


In the first phase of application development, you evaluate the application and break it down 
into a number of User Objects. 


Phase 2 of Application Development 


In the second phase of application development, you describe all User Objects for the core 
system, see Figure 1-6: 


1. Describe the Application as a User Object Type: 


Edit the object type description into an ordinary text file using any text editor. Make the 
description in the high-level language called OTDL (Object Type Definition Language). 
See Section 3.7.6, Object Type Definition Language (OTDL) for more information about 
OTDL. 


2. Process the OTDL text file with the Object Type Builder to generate object type 
information. See Section 3.7.3.1, Object Type Definition for more information. 


3. Install this object type information into the core system to identify and describe the object 
type to all other users. This is done outside the Object Type Builder. See the Advalnform 
Basic Functions User’s Guide. 


The description resulting from the above steps is used by the core system to create a distributed 
object management scheme. All applications within the Advant OCS system must be described 
as objects. The distributed object management provides all necessary interaction between the 
objects in the system. See Figure 1-7 below: 


Advant IMS Operator 
Controller Station Station 


| 
Core system 


Network 


Figure 1-7. Core System Connects all Objects 


Phase 3 of Application Development 

In the third phase of application development, you finalize the User Object: 

4. Implement (program) the User Object. See Section 3.7.7, Programming the Operations. 
5. Build arun time environment and install it. See Section 3.7.3.8, Build. 


Except for step 3, both phases 2 and 3 are covered by Object Type Builder. In the next phases of 
application development, you create and configure object instances and execute (run) and test 
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those instances (see Figure 1-6). For detailed information on how Object Handling is carried 
out, see the Advalnform Object Handling User’s Guide. 


Phase 4 of Application Development 
6. Configure instances using Object handling 


7. Build a user interface to the objects e.g. with AdvaInform Display. 


1.8.4 Functions 


1.8.4.1 General 


Object Type Builder consists of the following tools: 

° ObjectBuilder - includes all the functionalities for User Object type development. 
° ObjectParser - tool for compilation of OTDL files and Operations 

° ObjectUtil - tool for maintenance and support functions 


° ObjectHandlers - tool for inspection of the status of, start and stop of the Object Handlers 
which correspond to the run time environment. Each Object Handler is the run time 
environment for a number of Object Types. 


1.8.4.2 Object Type Information 


Object type information is summarized in Figure 1-3. Using an object-oriented approach, you 
can describe the application as a User Object. In Object Type Builder, you use the description 
language OTDL to describe the application as a User Object. OTDL contains the facilities you 
need to describe inputs, outputs, public data, supported data requests, events and the operations 
available to other applications. 


As mentioned in Section 1.8.3, Development of User Objects, all applications that use the core 
system must be described as objects. This corresponds to phase 2 of the application 
development. The tools ObjectParser and ObjectUtil give the support to define new object 
types for the core system according to phase 2. By using the tool ObjectBuilder you cover both 
phase 2 and 3 and will be able to build complete User Objects. 


1.8.4.3 Installing Object Type Information 


When you have processed the OTDL file and installed the resulting object type information, any 
instances of the object type are known to all other applications. You must program the object 
type and build a run time environment before you can create instances though. As mentioned 
earlier, the installation of object types is done outside the Object Type Builder and described in 
Section 3.7.4, Updating Object Type Directory. 
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When the instances are installed, it does not matter where they reside. The core system provides 
identical methods to access all known applications. 


Display Presentation: Operator 
From the display, the objects| | Station or 

are accessed identically no Advalnform 
matter where they reside. Display clients 


Advant 


Controller Station 


Applications Objects 


Third-Party Tools 


yO Objects 


Figure 1-8. Example of a Display Presentation 


1.8.4.4 Programming 


When you have created and processed the OTDL file you can start the programming of the User 
Object. 


You program the application code (operation code, see Figure 1-3) in C++ or C. You can use 
Pascal and FORTRAN programming languages as complements (called as library routines). 
By declaring them according to ANSI-C they can be called from the application code written in 
C++. 


Enter the program code with a text editor and process it using Object Type Builder. The result is 
a completely programmed application. You only need to write the actions related to the 
application. You can communicate with other applications and interact with databases and 
operating systems without any specific programming. 


Since the application (operation) code can ignore input and output details, execution, operating 
system interaction, etc., it is truly application-oriented. The application code includes only what 
is needed for you to perform application work. 


The User Object program is divided into Normal and Command Operations. Normal Operation 
is activated as a result of any of these four actions: 


1. Therun time environment is started for the first time after start-up. 


2. The object is activated by the scheduling function (configured to execute at certain time 
intervals). 


3. The object is activated by an event (a trigger request becomes true). 


4. The object is activated by the command NormalOperation for example from another 
Object or from a User API program. 


Each Command Operation corresponds to a command definition in the OTDL and contains the 
routine to execute when the command is received. 
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1.8.4.5 Test and Debug 


Use the object configuration display to configure instances for test. verify results by observing 
input and output values, event messages etc. If you can’t solve a problem by observing the 
behavior start a debug session according to Appendix I, Debugging of User Object Applications 


1.8.4.6 User Object example: Integration of Third-Party Software 


With the execution support provided for User Objects, various third party softwares can be 
executed at cyclic intervals and on process events or operator and application commands. 
Examples are Spreadsheet programs and Optimization packages. 


Object Type Builder lets you encapsulate third-party software into the IMS Station and thus into 
the Advant OCS. 


Example You have a third party software that needs data from the process to execute. As a 
result it returns some calculated information that shall be possible to present. The executions 
shall be possible to do on an event from the process (a valve is closed), on request from any 
application or operator, or for example once every hour. 


To solve this you create a User Object Type with a number of input connections towards process 
object types. One of them is a Digital Input which can generate an event trigger when the valve 
is closed. The User Object Type has a number of attributes to store the results in. It will also 
have a command so that the Operator (or another User Object) or any application can request the 
third party software to be executed. 


Sia by a (3) SO 
operator reques Obiect 
instance (5) Execute Third 
Operation Part 7 
Result Code Toor 
presented (2) Result 
for User 


The object 
is (4) 
configured 
to execute 
at certain 
intervals 


(Advalnforr 


Process event that 
triggers the execution 
of the object 


Figure 1-9. Integration of Third-Party Software 


1. Through the input connections, data collections and event triggering is solved. 


2. Through the attributes - displays can be built using AdvaInform Display to present the 
result. The result is also available as columns in an Oracle table making it possible to see 
the results from a PC equipped with Oracle tools. 


3. Through the command NormalOperation any application can request for a manual 
execution. 


4. The object instances can be configured to execute at cyclic intervals. 
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5. The interactions with the third party software is done in C. If the third party software is a 
library you link it into your User Object run time environment. If it is a separate program 
you interact with it using ordinary C functions (POSIX compliant). 


NOTE 


The basic object type coExecutor provides the majority of this functionality. 
As the source code for that object type is provided the easiest way to solve your 
problem is to extend the implementation of that type. 


1.8.4.7 Run Time Environment 


The last step in creating the application is configuring and building the run time environment for 
the object type(s). A run time environment must exist before you can configure instances. 
You can build it interactively using Object Type Builder. 


The run time environment is provided with Object Handling and gives you: 
° Input retrieval 

° Output storage 

° Error treatment 

° Reception and execution of command requests from other applications 
° Serving requests from other applications, displays, etc., for public data 
° Event and alarm sending 


° Scheduled and triggered (event-driven) execution. 


Advant IMS Operator 
Controller Station Station 


Core system 


Network 


Core system 


IMS 


Run Time 
Environment 


User Objects 


Figure I-10. Core System and the Run Time Environment 
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1.8.4.8 Object Instances 


You use the Object Handling configuration tool to create and configure instances of User Object 
Types. When the first instance is created, a relational DB table is automatically created. This 
table is referred to as an instance table. Each attribute of your object type has a corresponding 
column in the table. Each instance has its own row in the table: 


Advalnform database 
pees Y instance table 


Attributes 


The 


Object attribute 
One instance, of the 
one row specific 

instance 


Figure 1-11. Relation between object type, instances and the Advalnform database 


1.8.4.9 Instance Execution 
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Object Handling’s instance configuration features for User Object Types let you configure User 
Objects to execute in a number of ways: 


° Time-controlled execution, at cyclic intervals, specific times or both and starting at an 
absolute time 


° Triggered execution, where events from another object activates execution. 


You define execution control, which is unique for every object instance, when you configure the 
object using Object Handling . 


User Objects are executed by a run time environment called Object Handler. Each Object 
Handler is a separate process and manages the instances of one or several object types. 


To configure an object instance, the object must be inactive (stopped). The configuration results 
are stored in the AdvaInform database. The object’s configurable attributes are updated in the 
object instance table. When you finish configuration, you start the object from the configuration 
tool. As a result of your start request the Object Handler starts the object. It reads all 
configuration information from the database and creates a primary memory copy of the 
attributes. This copy will thereafter be identical to the corresponding database table row in the 
database as shown in Figure 1-11. 


When a User Object is executed, the following occurs: 


1. If the object has input connections, subscriptions to the connected objects will be sent and 
the object will be dormant waiting for the data to arrive. This is the case, no matter how the 
User Object was started. An object without input connections will just ignore this phase. 


1. See also Chapter 3, Configuration and Application Building. details for information on executing control for 
written the object. 
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The data will be waited for during a certain time. If all data does not arrive within that time 
or if the reading from a connection fails, the following error handling takes place. 


If the flag Suppress error actions is set, the execution will continue with step 2 below. 
The connection(s) that were not successful are marked with an error. If the Suppress error 
action flag is not set, the execution will be terminated. If the attribute STATUS exists for 
the object type, the instance will get its STATUS bit error set. A system message will be 
sent. 


NOTE 


The next execution of the object will take place even if one execution has failed. 
If that one also fails, the only difference is that no system message will be sent. 


When all data has arrived successfully, the object starts to execute. Depending on how the 
object was started, different sections will be executed. In all cases, except when a 
command to another Object Operation is received, the Normal Operation is executed. 


During execution of any operation, commands can be sent to output object connections. 
These commands will be sent asynchronously, that is, the sending object does not wait for 
the result. As soon as the command is accepted by the core system, the object continues its 
own execution. 


If, during execution of an operation, Normal or Command, a run time error such as divide 
by zero occurs, the object instance will be stopped, a system message is sent and the 
objects STATUS error flag will be set (if existent). 


When the objects operation execution is finished, any attributes modified during the 
execution are written to the objects data row in the IMS database. If no modifications 
occur, no writing takes place. The saving can be suppressed using Object util or using 
function calls from within the object. 


Figure 1-12 below shows the object execution over time. 


Step 1 Step 2 Step 3 
(optional) 
Data requests Data received Execute Save 
operation(s) modified 
attributes 
Commands in the 
database 
Dormant 
————— 


1 i | 


Figure 1-12. Time diagram for User Object execution 
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A User Object can generate events. The event functionality can be used between User Objects 
(and other applications as well) to start and to read data from each other, on an event basis. 
The User Object that wants to be started event driven, sets up a read on event subscription on 
another object. When that object signals that the event has occurred, the core system will start 
the subscriber object. This functionality is also referred to as triggering. 


Each event that a User Object may issue are declared in the Object Type definition (OTDL file). 
The sending of the event is requested in your application code, the operations, when the 
appropriate situation occurs. The events can be subscribed upon by other objects. 


1.8.4.11 Messages to the Message Log and the Event and Alarm system 


1.9 User Interface 
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The Object Type Builder supports the sending of messages to a local message log (Master- 
provided that the AdvaInform History option is installed) and to the event and alarm 
subscribers. The subscribers are typically the event and alarm lists in Operator Stations. The 
sending of messages is requested in your application code, the operations, when the appropriate 
situation occurs. 

You can also use Object Type Builder for implementation of alarm acknowledge (Master). 


The User interface interaction is thoroughly described in Chapter 3, Configuration and 
Application Building. 
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2.1 Site Planning Environment 


2.2 Setup 


2.2.1 Hardware 


Refer to the Advant Station 500 Series IMS User’s Guide for information about site planning, 
installation and diagnostics of the IMS. 


A C++ compiler is included in the option (licensed for one concurrent user). 


For details regarding the hardware, refer to the Advant Station 500 Series IMS User’s Guide and 
the relevant Advant Station 5xx Hardware User’s Guide. 


2.2.2 Software installation and removal 


Generally, the AdvaBuild Object Type Builder software is loaded onto the Advant Station at the 
factory prior to delivery. Therefore, you generally do not have to load the software. 


If you, for some reason, have to install or remove the Object Type Builder software, refer to the 
Advant Station 500 Series IMS User’s Guide for instructions. 


2.3 Shut-down Procedures 


The Object Type Builder has the ability to start and stop the run time environment for the 
respective Object Types. Except for this, there are no continuously running programs included 
in the software. The other parts of the Object Type Builder consists of 4 utilities. These utilities 
you terminate by: 


° Enter Quit or Exit to terminate ObjectBuilder. 
° Enter Exit to shut down ObjectUtil. 
° Enter Exit to shut down ObjectHandlers. 


° Enter exit to terminate the Object Type Builder terminal window. 


2.4 Start-Up Procedures 
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The Object Type Builder consists of four utilities contained in a specific environment: 


ObjectBuilder, ObjectParser, ObjectUtil and ObjectHandlers. 
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You start the Object Type Builder from the IMS menu AdvaBuild menu by selecting Object 
Type Builder: 


= Advant Station 500 Information Management Station | ) | | 
File Station AdvaBuild Advalnform AdvaTalk Session Settings Help | 


Object Type Builder 


Figure 2-1. Selecting the Object Type Builder from the IMS main window 


As a result a Terminal window is started with 4 utilities available, see Figure 2-2 


IMS Object Type Builder 


Figure 2-2. Object type Builder terminal window 


The following commands are now available: 

¢« Enter ObjectBuilder to start the ObjectBuilder. 

¢ Enter ObjectParser to start the ObjectParser. 

¢ — Enter ObjectUtil to start the ObjectUtil. 

e Enter ObjectHandlers to start the ObjectHandlers. 


From the terminal window, you can select directories to work with and other tools provided in 
the system (such as the editor you prefer). 
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2.5 Product Verification 


The utilities display their current version when activated. 
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Chapter 3 Configuration and Application Building 


3.1 Design Considerations 


3.1.1 Selecting the right IMS tool 


IMS provides you with a number of tools for application building: 
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User Objects: AdvaBuild Object Type Builder and AdvaInform Object Handling 
AdvalInform Calculations (Master only) 
AdvalInform User API, hereafter called User API. 


Tools for development of database applications (AdvaInform SQL Connect, AdvaInform 
SQL Connect Programming, and Programmer - Pro*C). 


It is important to know when to select which tool and how to combine the tools to solve your 
application needs. 


The most important reasons to use User Objects are the facilities that are provided by User 
Objects but not by the User API: 


User Objects automatically provide server functionality. If other applications need to 
subscribe on data from your application or interact with it, you need that server 
functionality. 


With User Objects (AdvaInform Object Handling) you get a configuration tool. It is easy 
to configure, start and stop the instances of the application. 


The User Object options provide facilities to build and to install the resulting run time 
environment that executes your application (the object instances). 


Finally, once you have learned how to work with User Objects, the productivity when 
creating new applications is very high. 


If none of the User Object facilities mentioned above are required, you can use the User 
API. There are also situations when it is easier to use the User API. For example, when 

you want to scan a large number of objects for some information, the User API is more 

flexible. 


As user API library functions can be called from within User Objects you can also choose 
to combine the strengths of both tools. 


When shall you use User Objects and when shall you use AdvaInform Calculations? 


The most important reasons to use User Objects are the limitations of the Calculation 
option: 


— User Objects automatically provide a server functionality which Calculations 
does not 


— The number of Calculation inputs and outputs are limited 
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— The Calculation script has limitations e.g it cannot call external libraries 


° The most important reason to use Calculations is the flexibility and the easy-to-use 
approach: 


—  Itis very easy to create and to modify calculations. It does not take many minutes to 
create a running calculation. 


— The algorithm can be easily changed and the execution of instances started again 
immediately. 


Most of the time it is rather obvious which tools to use when you compare user objects with the 
tools for development of database application. 


See also Advant Station 500 IMS User’s Guide for comparison of different tools. 


3.1.2 User Object design 


Before beginning this section, please see Section 1.7, Terminology, for an introduction to, and 
description of, the terminology used in this chapter. 


To give your User Objects the best possible design, consider the following when you are 
designing User Objects: 


° Will you split your application into one or several User Objects? 


Each object execution is done in three steps. 1) All input data is requested (the connections 
are read), 2) the operation code is executed, and 3) all attributes that have been changed are 
updated in the data base!. See Section 1.8.4.9, Instance Execution for more details. 


Object types with many connections demand more resources and will be slower to execute 
since the object must wait for the connection data to arrive before it starts to execute. 
If there are conditions for the object to execute, the design can be altered as follows: 


Alternative 1: Split up the application into two User Objects, one large and one small. 
Let the small one evaluate the conditions and determine if the large application 
should execute or not. When all conditions are fulfilled, start the large User Object 
with a command. 


Alternative 2: Split the data retrieval in one part that is read by the User Object 
facilities and one that read with the user API library once the initially read conditions 
are evaluated. 


Since large applications with many inputs take longer time to prepare for execution, do not 
build extremely large objects. 


° How many attributes will you give the User Objects? What information will be stored in 
attributes? 


A large number of attributes means a large number of columns in the User Object’s 
instance table, so you may want to split the application into several User Objects. Restrict 
the attributes to public information, that is information required by other applications, and 
to configurable information. 


1. This is configurable using the ObjectUtil utility or using functions calls from within the operations. 
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Do not define help variables used only as part of the programming of the application as 
attributes. 


° How will you get the best performance? 


Avoid updating attributes unless it is really necessary. Each time an object executes and 
one or several attributes are updated, they are by default written to the data base!. 

An object that always updates attributes generates a larger load on the system than an 
object that updates attributes only when changes have actually occurred. 


You can deactivate the update to the data base to improve the performance. Appendix D, 
ObjectUtil Commands, contains the details on how. If this can be allowed, e.g. when the 
data source is outside the information management node and the object only works as a 

data mirror, this will enhance performance for objects with frequently updated attributes. 


You can also disable and enable the data base update using the programming functions 
described in Section 3.7.7.7, Summary - Available variables and functions. This should be 
considered in your design. 


° Which type of output connection should you use? 


In general you must distinguish between asynchronous and synchronous execution. 
Asynchronous means that your command is sent to the receiving object but the sending 
object will not wait for an answer, nor can it receive any return parameters. The most 
important aspect with asynchronous commands is the performance. You can continue your 
execution without waiting for other objects actions. 


Synchronous commands on the other side gives you the ability to receive answers from 
other objects. You should use synchronous commands when you synchronize the 
execution of different objects or you have to get answers back on your commands. 


A summary of the 3 available command types: 


— The ordinary asynchronous output is the way output has been performed in previous 
versions of User Object. The output command is executed immediately when invoked 
and no return parameters can be used. 


— If your object type has several output connections, it is preferable to use the 
asynchronous buffered output. Asynchronous buffered output is default. 
The asynchronous buffered output, buffers the execution of the commands until the 
operation is performed and then executes all the command calls at the same time. 
The commands are thereby not given any relative order but this gives by far the best 
performance when you have more than one command to execute. No return 
parameters can be used though. 


NOTE 


When using this mode, you can not send more than one command to each output 
connection. 


— Ifyou need the executed command to return values, you should use the synchronous 
output connection. It synchronizes the executed command with other objects and 
gives you the return parameter before the next command can be executed. 

Because the object handler is idle while waiting for the command completion, 
the performance is not as high as with asynchronous output connection. 
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To select one of the above output connection types you use predefined functions in the 
operation code. 


In addition you can also choose to perform your output using a User API library function. 
This gives you some additional flexibility as you can choose the output object type more 
freely and even change output object between executions. 


Will your User Objects be generic or specialized? 


When you use object connections to describe inputs, the User Object is specialized as the 
inputs must be read from instances of the specified object types. If you want more generic 
User Object Types you should use Single Connections for inputs but then you loose the 
ability to check the status of the received data. 


How will you treat errors? 


You can suppress error actions by describing inputs as suppressed during the object type 
design, which means that failure to read that input object data is not fatal. The User Object 
may continue to execute using defaults or may simply ignore the input. (Decided by the 
implementation). 


To what degree will you use inheritance in the design? 


You can use inheritance of ready-made object types, which include essential attributes and 
a number of useful commands, when designing User Objects. It is strongly recommended 
to always inherit one of those object types. 


You can also use inheritance between your own User Objects for cost-effectiveness. 
See Section 3.5.1.4, Inheritance, for more information on how to make these choices. 


3.1.3 Integration of process data from external vendors 


In many Advant OCS deliveries there are PLCs, DCS systems, or other external systems (called 
EC) that cannot be connected to the Advant OCS via Advant Controllers. Example reasons 
include: 


The EC communicates through IEE802.3 carriers. No such facility currently exists on our 
Gateway solutions. 


There are no Advant Controllers at the site. 


Another vendors information management or Lab computer needs to be connected. They 
are not suitable to connect through an Advant Controller. 


The most important requirement is to access external data from Advant clients (AdvaInform 
History, AdvalInform Reports, Event and Alarm treatment, Operator Station Displays, User 
Objects, Calculations) and to read and send information to the External Computer. 


The User Object options AdvaBuild Object Type Builder and AdvaInform Object Handling 
provide a solution to these requirements. The principles for this are described in Appendix D, 
ObjectUtil Commands. 


3.2 Capacity and Performance 


See the Advant Station 500 Series User’s Guide for details on Capacity and Performance. 
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3.3 Software Setup 


Start the AdvaBuild Object Type Builder from the IMS main window as described in Section 
2.4, Start-Up Procedures. This starts a dedicated terminal window, see Figure 3-1 below, where 
you can use the following commands: 


° Enter ObjectBuilder to start the ObjectBuilder. 
° Enter ObjectParser to start the ObjectParser. 
° Enter ObjectUtil to start the ObjectUtil. 


° Enter ObjectHandlers to start the ObjectHandlers. 


Type Builder 


‘Welcome to ObjectBuilder 1.2-0 


Available tools: 


ObjectBuilder 
ObjectHandlers 
ObjectUtil 


'1$ ObjectBuilder 
‘JOBJECT BUILDER 1.2-1> oper 
OPERATION DESIGN> select ai 
‘JOPERATION DESIGN: ai> list 
‘| Command operation(s): 

SELECT Implemented 

DESELECT Implemented 

ORDER Implemented 

ACKNOWLEDGE Implemented 

GETVALUE Implemented 
Normal operation(s): 
i Normal operation 1 ABB_standard_normal_operation 
OPERATION DESIGN: ai> §j 


Figure 3-1. Object Type Builder terminal window 


3.4 Tutorial 
3.4.1 Average Example 


3.4.1.1 Requested Functionality: An Average Calculation 
The functionality of the average object is as follows: 


° The object type reads three compulsory and three optional floating point values, calculates 
an average value, and compares the average value with an upper and a lower alarm limit. 
The result is stored in an attribute called Value. Alarm status bits are refreshed according 
to the current limit check situation. In a Master system the example also shows how to 
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support alarm sending and alarm acknowledgment. The Master specific things are 
underlined in the example. Events are generated when the alarm limits are transgressed 
and when the object returns into normal state again. 


Three commands are supported. One is a user-defined command to change the alarm limits 
called ChangeLimit. The other two are the compulsory commands for support of alarm 
treatment in a Master system, ACKNOWLEDGE and ORDER. 


Two events to signal the individual transgression of the alarm limits and one that signals 
any transgression to any other object that subscribes to such triggering, are defined. 


Lets brake the requirements down into User Object terminology: Normal Operation, Input, 
Output, Commands, Subscriptions, Events: 


Algorithm (Normal Operation) 


Calculate the average value of a number of input temperatures and verify that the result is 
within certain limits (Normal Operation). 


Input 


— The measured value of 3 to 6 floating point inputs, depends on the number the user 
configures. 


— One upper and one lower limit (Attributes). 
Output 
The calculated average value (Attribute) and a status (Attribute). 
Events 
When the value is outside a limit and when it returns back into normal state. 
Commands 
ChangeLimit: A command to change the limits (Command Operation) 


ORDER: To the handle the information from Alarm lists that an unacknowledged 
alarm exists 


ACKNOWLEDGE: To handle acknowledge from Alarm Lists. 


Subscriptions: 


The value and the status are convenient to address as one entity from subscribers. Thus, a 
subscription that packs them together in a list is defined. 


3.4.1.2 OTDL File - average.def 
The first step is to write the OTDL file. The text file below shows the resulting OTDL file: 


3-6 


NOTE 


Comments in ordinary font and the OTDL in courier. 


Uses default inheritance. The attributes NAME, DESCRIPTION and STATUS are inherited. 
The instances are configured by the Object Configuration tool. 


average /descr (“Average calc”) /tool (coct) 
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/typeDef 

TdStatus: Bitset32 ( 
loLimError: Bit (8); 
hiLimError: Bit (9); 


unacknowledged: Bit(13);); 


endTypeDef 


/part 
// Name Data type 
loLim: 
hiLim: 
value: 
limTR: 
endPart 
/part 
objl: 
obj2: 
obj3: 
endPart 
/part 
optObjl: 
optObj2: 
optOb 43: 
endPart 
/subscription 
avrgCyclic: 
endSubscription 
/command 
changeLimit: 
dummy; (); 
ORDER: 


(averageAttribute) 


Float[8,3] 
Float[8,3] 


Float [8,3] 
IntShort/input /default (3) 


(compConnections) 
connect Float 
connect Float 


connect Float 


(optConnections) 
connect Float 
connect Float 


connect Float 


(IntSmall 


/descr (“Attributes for result and limits”) 
Dir User Number Remark 

/default (20.0) /configure/range (-10.0:300.0); 
/default (90.0) /configure/range (50.0:500.0); 


/default (60.0); 
/configure /range(1:300); 


/descr(“Compulsory single float conn’s”) 
[8,3] 
[8,3] 
[8,3] 


/input; 
/input; 
/input; 


/descr (“Optional single float conn’s”) 
[8,3] 
[8,3] 
[8,3] 


/input/optional; 
/input/optional; 
/input/optional; 


(value, status) ; 


(IntLong /input limitLoHi, 
[8,2] 


input opCode, 


Float /input newLimit); 


IntShort 
IntSmall 


Boolean 


/input opProp, 
/input typeOfReq, 


input eventLog, 


IntLong /input dialogId, 


Float 


IntLong 


8, 


2] /input aValue, 


input dValue, 


IntSmall 
IntShort 
ACKNOWLEDGE: 


/output status, 
/output textIndex) ; 


(IntSmall /input opCode, 


IntShort 
IntSmall 


Boolean 


/input opProp, 
/input typeOfReq, 


input eventLog, 
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IntLong /input dialogId, 


IntSmall /output status, 


IntShort /output textIndex) ; 
endCommand 
/event 


eventHiLim: (); 


eventLoLim: (); 


eventAnyLim: (); 


endEvent 


end 


3.4.1.3 Normal Operation File - avrgNormop.c 


The average object type has one Normal Operation. It calculates the average value of the input 
connections and stores the result in an attribute. After the calculation, a limit check is done with 
corresponding event handling. Events are raised when alarm limits are transgressed or when 
returning to normal state again. Most of this is Master specific. 


// The first time the Normal Operation is accessed it initializes the 
// event handling 
switch (reasonForActivation) { 

case coFirstActivation: 


sendEventData.useSystemTime = gcFalse; 


sendEventData.objectEngUnit[0] = 0; 


sendEventData.processSection = 0; 


sendEventData.valueType = DCX_REALV; 


sendEventData.errTreatReference = LimTR; (Master) 
sendEventData.errTreatReference = 0; (MOD 300) 


sendEventData.blockConditions[TdAlarmBlock] = gcFalse; 


sendEventData.blockConditions[TdPrintBlock] = gcFalse; 


sendEventData.blockConditions[TdRepFailBlock] = gcFalse; 
break; 
default:; 
} 
// Calculate the average value. Handle the optional connections 
int. count = 3; 
value = objl + (obj2 + (0bj3)); 
if (optObj1){ value = value + (*optObj1); count++; } 
if (optObj2){ value = value + (*optObj2); count++; } 


if (optObj3){ value = value + (*optObj3); count++; } 
value = value / count; 


Check for alarm limit transgressions or for returning from such transgressions. Generates events 
when going into or leaving alarm state. 


if (value < loLim) { 


if (!STATUS[loLimError]) { 


3-8 3BSE 001 012R0501 


AdvaBuild® Object Type Builder User’s Guide 
Section 3.4.1 Average Example 


STATUS [loLimError] = (gcBoolean) true; /*generate alarm on*/ 
sendEventData.valueFloat = value; 
sendEventData.eventReason = DCX_ALARM_ON; 
sendEventData.eventAttribute = DCX_ELO_LIM1; 
sendEvent(); /* raise events */ 
eventLoLim (); 
eventAnyLim (); 

} 

else if (STATUS[loLimError]) { 

STATUS [loLimError] = (gcBoolean) false; /*generate alarm off*/ 
sendEventData.valueFloat = value; 


sendl 


send 
sendEvent (); 
} 


(value > 
BE 


if hiLim) 


{ 


STAT 


sendl 


sendEventData. 


send 


sendEvent (); 
eventHiLim 


eventAnyLim 


Lf 
STAT 


else 


sendl 


sendEventData.eventReason 


send 


sendEvent (); 


returnOmfCode 


EventData.eventReason 


EventData.eventAttribute 


(!STATUS [hiLim 
US [hiLimError] 


EventData. 


EventData. 


(STATUS [hiLim 
US [hiLimError] 


EventData.val 


EventData.eventAttribute 


omfCAP_SUCCI 


DCX_ALARM_OFF; 


DCX_] 


ELO_LIM1; 


Error]) 


{ 


(gcBoolean) 


true; /*generate alarm on*/ 


valueFloat = value; 


eventReason DCX_ALARM_ON; 


DCX_1] 


eventAttribute 


ELO_LIM1; 


(); 
(); 
Error]) { 


(gcBoolean) 


false; /*generate alarm off*/ 


lueFloat = valu 


’ 


DCX_ALARM_OFF; 


DCX_] 


ELO_LIM1; 


ESS; 
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3.4.1.4 Command Operation ChangeLimit - avrgChangeLimit.c 


A new loLim must be smaller than hiLim and a new hiLim larger than loLim. 
When a new alarm limit is accepted, the Normal Operation is executed. 


switch (limitLoHi) { 
case 1: 
if (newLimit<hiLim) { 
loLim=newLimit; 
normalOperation(); 
} 


break; 


case 2: 
if (newLimit>loLim) { 
hiLim=newLimit; 
normalOperation(); 
} 
break; 
default:; 
} 
returnOmfCode = omfCAP_SUCCESS; 


3.4.1.5 Command Operation ORDER - avrgOrder.c (Master) 


/* Set the alarm unacknowledged status bit */ 


if (opCode ==dcSET_UNACK_DCX) { 


STATUS [unAcknowledged]=(gcBoolean) true; 


returnOmfCode = omfCAP_SUCCESS; 


status = dcGRANT; 
} 


else { 


returnOmfCode = omfCAP_PARAMETER; 


status = dcNOT_ALLOWED; 
} 
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3.4.1.6 Command Operation ACKNOWLEDGE - avrgAcknowledge.c (Master) 


/* Acknowledge the alarm unacknowledged status bit */ 
/* Respond to the acknowledge so all alarm lists in the control */ 


/* network or plant network are updated. */ 


if (opCode ==dcACKNOWLEDGE_DCX) { 


STATUS [unAcknowledged] = geFalse; 


acknowledgeLists (1); 


returnOmfCode = omfCAP_SUCCESS; 
status = dcGRANT; 
} 


else { 


returnOmfCode = omfCAP_PARAME 


4g 
x 

ys) 
~ 


status = dcNOT_ALLOWED; 
} 


3.4.2 User API Examples 


Introduction 


This example shows a User Object that use the new feature, as from User Objects 1.3, of calling 
User API routines from inside the User Object. 


General 


The purpose of this example is to describe the usage of User API routines in your User Object 
step by step. The procedure for this is as follow: 


Write the library routine declaration. 
Implement the routine against User API. 


Compile the routines to object files. 


Using Object Builder, add the library routines. 


1 

2 

3 

4. Add objecttype to the system. 

5 

6. Assign the routines to your objecttype. 
7 


You can call the routine from inside your objecttype. 
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3.4.2.1 Example ai2History 


3-12 


Description 


The example shows how to achieve event driven history logging without an external User API 
application. The example will use library functions based on the User API facilities. The func- 
tions can be called from User Objects. The idea of the example is that it will read the value from 
an AI object and write it to an asynchronous log. 


How to use 
Use the ready made scripts to build the ai2History object as user ocsmgr. 


1. Run the script which builds the object type: 
/opt/advant//ObjectBuilder/examples/userapi_examples/ai2History_build. 


2. Run the script which builds the object handler: /opt/advant//ObjectBuilder/exam- 
ples/userapi_examples/ai2HistoryHandler_build. 


3. Because the ai2History is a new object type, you must run a tdgen as described in Section 
3.7.4, Updating Object Type Directory. 


Functionality 
The functionality of the ai2History object is as follows: 
e The object type reads the value of an AI object and writes it to an asynchronous log. 


e Itconsists of one input connection and two library routines. The input connection is a DI 
event trigger input and the normal operation of the User Object will only be executed on a 
positive flank i.e. when the value of the DI goes from zero to one. 


¢ The User API routines consists of two routines, the first one “readAI_VALUE” reads the 
value from the specified AI object, the second “writeHistory” writes a value to a specified 
asynchronous log. 


e The routines requires the name of the AI object and the History log object. 


¢ Errors that occur in the object originate first of all from the routines based on User API ie. if 
you submit an object name that do not exists. Because the object names are transferred 
through attributes, check if the object names are valid is not possible until the routines have 
been executed. 


Algorithm (Normal Operation) 


Each time the operation is executed it reads the value from the specified AI object and writes 
it to an asynchronous log. It also updates the routines call status attributes. The normal oper- 
ation can be executed either by a trig from the DI input or a scheduled execution, or both. 


Input 
DI_TRIGGER: Input connection of the DI trigger. 
Output 


none. 
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Attribute 
aiObj: The name of the AI object that the value shall be read from. 
logObj: The name of the asynchronous log to insert values in. 
aiCallStatus: The most recent status of the “readAI_ VALUE” call. 


logCallStatus: The most recent status of the “writeHistory” call. 


User API library routines 
readAI_VALUE: Reads value from an AI object 


writeHistory: Write a value to an asynchronous log object. 


Events 
none 
(— User object >\ 
User API_connection User defined Library 
logObj Library routines 


aiObj writeHistory(char * Obj ame, 
User API_status = bees 

: char* status, 
aiCallStatus int statusLength 
logCallStatus L_VALUE(char* objectName, 

2 int* value, 

Connection char* status, 
DI TRIGGER int statusLength 


c A e. User API library 


DI History logs 
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3.4.2.2 Read Al Routine - readAl_ VALUE.h 


At least User API 1.2-1 must be installed before starting to build and compile the user api rou- 
tines. The complete path for the User API files must be included. Use the apiMake-file that is pro- 
vided by ObjectBuilder to compile the user api routines: 
$/opt/advant/ObjectBuilder/examples/userapi_examples/apiMake 
readAI_VALUE 


The user api routine header file: 

#include </opt/advant/UserAPI/include/bciUserAPI.h> 
#include </opt/advant/UserAPI/include/bsUserAPI_def.h> 
#include <omf_AI.h> 


#ifdef cplusplus 
extern “C” { 
#endif 


/* 

PARAMETERS 

objectName[in]Name of the object instance 

value[out]Pointer to a double where the return value will be 
stored. 

status[out]Text information about the status of the UserAPI call. 
statusLength[in]Length of the information. 


DESCRIPTION 
The readAI function is used for reading the 


value from an AI object. 
*/ 


BciStatus readAI_VALUE(const char* objectName, 


double* value, 
char* status, 
int statusLength) ; 


#ifdef _ cplusplus 
} 
#endif 


3.4.2.3 OTDL File - ai2History.def 


The first step is to write the OTDL file for the ai2History object type. It uses default inheritance 
which means that the attributes NAME, DESCRIPTION and STATUS are inherited. Instances 
can be configured by the Object Configuration tool. The text file below shows the resulting OTDL 
file: 


ai2History /descr(“Access User API from inside User Objects”) 
/tool (coct) 


/part (UserAPI_Parameters) /descr(“Parameters to library routines”) 
logObj : String[81] /default(““) /configure; 
aiObj : String[21] /default(““) /configure; 


3-14 3BSE 001 012R0501 


AdvaBuild® Object Type Builder User’s Guide 
Section 3.4.2 User API Examples 


endPart 
[iX (Snes Present the recent status of the library routines -—--—-— * / 


/part (UserAPI_Status) /descr(“Status of the library routines”) 


logCallStatus : String[81] /default(““) /configure; 
aiCallStatus : String[81] /default(““) /configure; 
endPart 
fe ase Define the DI trigger -----— */ 


/part (CONNECTION) 
DI_TRIGGER:connect DI(din_abl_dcx) /input /optional /trigger (EVENT) ; 
endPart 


end 


3.4.2.4 Normal Operation File - ai2History_normOp.c 
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The ai2History object type has one Normal Operation: 
// KKEKKKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKKKKKKKKKKKKKKK 


// Normal operation for User Object ai2History. 
// KKEKEKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKKKKKK KKK KK 


doublevalue; 
gcBooleantriggerState; 
char aiStatusString[81]; 
char logStatusString[81]; 


// KKEKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK KKK KKK KKK 


// Check that the parameters to the UserAPI 


// routines are configured. 
// KKEKKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKKKKKKKKKKKK KKK 


if (aiObj.currentLength() == 0 | | logObj.currentLength() == 0) 
{ 

aiCallStatus = “Parameters not configured”; 

logCallStatus “Parameters not configured”; 

returnOmfCode omfCAP_SUCCESS; 

return; 


switch (reasonForActivation) { 
case coFirstActivation: 
if (trace) cout << “First activation” << endl; 


if (DI_TRIGG 


ea 
w 
o 


prevTriggerState = DI_TRIGGER->STATUS [coDI: : VALUE]; 
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} 


break; 


case coViaCommand: 
break; 


case coCyclic: 


if (readAI_VALUE (aiObj, &value, (char*) aiStatusString, 81) == 
bciSUCCESS) 
{ 


if (writeHistory (logObj, (float) value, (char*) 


logStatusString, 81) != bciSUCCESS) 
{ 
logCallStatus = (gcString) logStatusString; 
aiCallStatus = (gcString) aiStatusString; 
STATUS[error] = gcTrue; 
return; 
} 
} 
else 
{ 
aiCallStatus = (gcString) aiStatusString; 
logCallStatus = “No data written to log.”; 
STATUS [error] = gcTrue; 
if (trace) cout << “Couldn’t read from the AI object, cyclic” 
<< endl; 
return; 
} 
aiCallStatus = (gcString) aiStatusString; 
logCallStatus = (gcString) logStatusString; 
break; 


case coTriggered: 
if(trace) cout << “Trigged execution” << endl; 
triggerState = DI_TRIGGER->STATUS[coDI::VALUE]; 


// KKEKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK KKK KKK KK 


// Determine if the execution was caused by a 
// positive flank, i.e the previous value was 


// zero and the present is one. 
Lf KKEKKKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKKKKKKKKKKKK 


if (!prevTriggerState && triggerState) 
{ 
if (trace) 


{ 


cout << “Positive flank” << endl; 
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prevTriggerState = triggerState; 


if (readAI_VALUE (aiObj, &value, (char*) aiStatusString, 81) 
== bciSUCCESS) 


if (writeHistory (logObj, value, (char*) logStatusString, 81) != 


bciSUCCESS) 
{ 
logCallStatus = (gcString) logStatusString; 
aiCallStatus = (gcString) aiStatusString; 
STATUS[error] = gcTrue; 
return; 
} 
} 
else 
{ 
aiCallStatus = (gcString) aiStatusString; 
logCallStatus = “No data written to log.”; 
STATUS[error] = gcTrue; 
return; 
} 
aiCallStatus = (gcString) aiStatusString; 
logCallStatus = (gcString) logStatusString; 
} 
else 
{ 
aiCallStatus = “No status available...... a 
logCallStatus = “No status available...... nS 


prevTriggerState = triggerState; 
} 


break; 


7] 


returnOmfCode = omfCAP_SUCCESS; 


Note _ If the first execution of the User Object is caused by a trig from the DI nothing happens. 
The reason for this behavior is that the object does not know the value of the DI before 
it is started. 


The data type “Float” in C is not represented in the same way as Float is in C++. In other 
words, DO NOT USE “Float” in your C User API routines, use “double” instead, if the 
parameter in the User Objects is of type Float. 
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3.4.3 ObjectBuilder and ObjectParser 


3-18 


The following section is a tutorial on how to implement the average object type, which is used 
as an example throughout this manual. 


See Section 3.7, Menus for a description of the text files used in this tutorial and Section 3.5.2, 
Implementation Steps for the implementation steps to perform. If you want to follow the tutorial 
in practice, use the average example from the directory: 


/opt/advant /ObjectBuilder/examples/ 
1. Use the OTDL file average.def. 
2. Parse it: 
S$ ObjectParser -TYPE average.def -—mode=parse 


ObjectParser version x.y-z 
ObjectPrecomp version x.y-z 


No syntax failure 
Object Type database not updated 
No files generated 


Repeat Steps | and 2 until the parsing is error-free. If you have problems identifying exactly 


what goes wrong, use the qualifier -mode=trace instead of parse. 


NOTE 

The parsing is done to verify that the OTDL is correct. If the OTDL is known to 
be correct, you can start directly with step 3. In step 3 the parsing of the OTDL 
results in the definition of a new object type in the data base and in the creation of 
the generic code for the object type. 

3. Start ObjectBuilder, add the OTDL file to it and compile it. 

$ ObjectBuilder 

OBJECT BUILDER> type 


TYPE DEFINITION> add average.def average 


TYPE DEFINITION: average> compile 


ObjectPrecomp version x.y-z 


No syntax failure 
File generation completed 
Object Type database updated 


TYPE DEFINITION: average> quit 


4. Leave ObjectBuilder and run the type directory utility. Rebuild the type directory and 
restart the node. This is thoroughly described in Section 3.7.4, Updating Object Type 
Directory 


NOTE 


This step may be done at a later stage. It is not necessary for the core system to 
know the object type until the run time environment (object handler) is installed 
in Step 8. 
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5. Program the operations. Use the Normal Operation and Command Operation files. Please 
remember that you must add at least one Normal Operation before you can create instances 
of the object type. 


Use the normal operation file avrgNormop.c and the Command Operation file: 
avrgChangeLimit.c, avrgAcknowledge.c and avrgOrder.c. Compile them until error- 
free using the ObjectParser: 


ObjectParser -NORMAL average avrgNormop.c 


ObjectParser -COMMAND average changelimit avrgChangeLimit.c 


ObjectParser -COMMAND average acknowledge avrgAcknowledge.c 


Kt Kr DH DW 


ObjectParser -COMMAND average order avrgOrder.c 


NOTE 


If the operations are known to be error free as is the case in this example, you do 
not need to make these test compilations with the ObjectParser. You can go 
directly to step 6. 


6. Add the operations to the ObjectBuilder. 
a. Select operation from the ObjectBuilder’s top level. 


b. Select the object type: average. 


$ ObjectBuilder 


OBJECT BUILDER> oper 


OPERATION DESIGN> select average 


c. Select normal operation. 
d. Add the Normal Operation source file as normal operation 1. 


e. Leave Normal Operation. 


OPERATION DESIGN:average> norm 


NORMAL DESIGN: average> Add avrgNormop.c 1 “Std Average calc” 


NORMAL DESIGN:average> exit 


f. Select Command Operation. Please note that by using the list command when 
Command Operation is selected, all of the object type’s commands are listed. 


OPERATION DESIGN:average> command 


g. Add the source file for the command changeLimit. 


COMMAND DESIGN:average>add avrgChangeLimit.c changeLimit 
“changeL” 


h. Add the commands ACKNOWLEDGE and order and then leave operation: 


COMMAND DESIGN:average> add avrgAcknowledge.c 


commandOperationName: acknowledge 


description: “Acknowledge” 
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3.4.4 EC -library 
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COMMAND DESIGN: average>add avrgOrder.c order “order” 


COMMAND DESIGN:average> exit 


OPERATION DESIGN:average> exit 


i. Build an object handler. Most object handlers contain more than one object type, so 
this step is not always repeated for each object type. The example below, however, 
assumes that only one object type is included. 


Priority is set to 5 in a scale of | to 10 where 1| is the lowest and 10 is the highest 
priority. The basic cycle time is set to 5, which means that the fastest cyclic interval 
within which an object can be executed is 5 seconds. 


OBJECT BUILDER> build 


BUILD> add averagehandler 

description: “Object Handler average O T” 
priority: 5 

basicCycleTime: 5 

BUILD: averagehandler>assign average 

BUILD: averagehandler> build 


Rebuilding Object Type Libraries 

average 

ar: creating libcotype.a 

Compiling Object Handler specific software 
Linking the Object Handler 


BUILD: averagehandler>quit 


Before starting the Object handler using ObjectHandlers, make sure that the new type directory 
that contains the new object type is properly installed and the IMS station restarted. 


The tutorial showing you how to use the EC library is included in Appendix G, External 
Communication Library. 
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3.5 Application Procedures 


3.5.1 Analyzing Applications and Designing User Objects 


3.5.1.1 General Design Considerations 


Using Object Type Builder, you can build your applications as User Objects. You must take the 
time to analyze and check key aspects of your User Object design as follows: 


1. 


In general, the interaction within, to and from your application is the most important factor 
when the application is split into User Object. Decide if the first split of your application 
will be into one or several User Objects. 


Check the requirements for data base design as described in Section 3.5.1.3, Data Base 
Design and the design constraints mentioned above. Correct your design accordingly. 


Add the configuration aspects. Will you use the AdvaInform Object Handling 
Configuration tool for instance configuration? ! Define which attributes will be 
configurable and the defaults and constraints of those attributes. 


Evaluate how you will use inheritance. i.e., inheriting from ready-made object types and 
inheritance between your User Objects. 


Include third-party software (libraries or tools) in your design. 


If necessary, include local variables, constants, procedures and functions common for a 
User Object. 


Once you have analyzed and resolved the above issues, you can start implementing User 
Objects with the Object Type Builder. See Section 3.5.1.2, Interaction with Other 
Applications/User Objects below. 


3.5.1.2 Interaction with Other Applications/User Objects 
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In general, the interaction within, to and from your application is the most important factor 
when the application is split into User Objects. Describe and consider the following: 


1. 


OO: ON 


Data from other objects (input connections), use single or object connections or the User 
API library? 


Output to other objects, using asynchronous, asynchronous buffered, synchronous output 
or the User API library? 


Preparations for first execution (Normal Operation). Eventually preparing the User API 
library requests. 


Triggered actions (Normal Operation) 

Schedule execution actions (Normal Operation) 
Requests that the object type must service (commands) 
Signal when something happens (events) 


Public data (attributes) 


The ability to create and use other configuration tools is available only internally within ABB. 
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9. A group of attributes to get if the object is described as input by another object 
(subscription) 


10. Design constraints as described in Section 3.1, Design Considerations. 


An example of process optimization using OPPIHOPP software follows. 


IMS 
Station 


Plant section # 1 C#1 
C#A raw mtrl : Plant section # 2 C#2 
supply Plant section # 3 C#3 


Common 


Figure 3-2. Example of Process Optimization with OPPIHOPP Software 


Requirements 


The OPPIHOPP third-party software is an excellent choice for plant optimization. The part of 
the plant that is to be optimized in this example consists of three identical sections producing the 
same output. Optimization can take place only if certain conditions are fulfilled. To check if they 
have been fulfilled, a few signals are to be read from the process on a repeated basis and their 
stability evaluated. Approximately 30 consecutive readings with one minute between each is 
needed. 


For each production section, a number of measured values need to be read and transformed into 
a format useful for the OPPIHOPP software. When the optimization is done, the results shall be 
stored in objects placed in Advant Controllers. They will be used as input to the process control 
performed by control loops. 


The optimization shall be possible to execute in manual and in automatic mode. In automatic 
mode the results are stored automatically, in manual mode they require operator intervention. 
Optimization results shall be possible to display on Operator Stations. 


Operators shall have the ability to switch between Manual and Auto mode. When in Manual 
mode they shall have the ability to start new optimizations and to store the last optimization 
results into the Advant Controllers. In Auto mode the optimization will take place once an hour 
and the result automatically stored into the controllers. 


It shall not be possible to execute the optimization more often than every 30 minutes. 
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Results of the analysis 


During analysis, the application is split into three User Object Types. Functional needs are also 
translated into attributes, Normal Operation functionality, commands, subscriptions and events, 
according to Items 1-10 listed previously in Section 3.5.1.2, Interaction with Other 
Applications/User Objects. In addition a usage of local Basic Objects is proposed to solve some 
of the functionality. 


The split into three Object Types is done due to the following, see also Figure 3-3 below: 


The conditions to perform the optimization can be evaluated by reading a limited set of 
data. A Coordination Object Type is created which is executed once a minute. It will build 
a local array of readings from the process to be able to make the evaluation of the 
conditions. It will also read the input from the Operators at each execution using three 
local Basic Objects as a communication base with the operator. (The operator can operate 
the Basic Objects using standard display elements included in his process displays:) 


The object ExecMode has an attribute that can be switched between two values meaning 
Auto or Manual mode. 

The object StartMan has an attribute that can be switched between two values meaning 
Start or Do Not Start manual optimization. 

The object StoreResult has an attribute that can be switched between two values meaning 
Store or Do Not Store the latest optimization results. 


The plant is divided into several sections. The work to be done is identical for each section. 
An object type, the Preparation Object Type, is created to take care of this. One instance is 
then required for each section. Further extensions with more sections will then be easy to 
handle. 


Finally, the optimization is embedded in a separate object type: Optimization Object Type. 
The optimization package is large and should not be executed unless really needed. When 
it is finished it stores the results into local Basic Objects which makes the result available 
for standard display elements. 
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Figure 3-3. Example of Optimization 


Coordination Object Type, One Instance 


° Function 


Reads the conditions for optimization each time it executes. Stores the values in a First In 
First Out array for appropriate verification of the last 30 values. 


Also reads the three Basic Objects ExecMode, StartMan and StoreResult each time for a 
correct handling of Manual mode and the different actions that may be requested by 
operators. 


In Auto Mode optimization will be done once per hour. In Manual mode the optimization 
is performed on request. 
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The optimization will be done as an interaction with other objects as: 
— Start the preparation objects and wait for them to finish 


— Starts the optimizer object when the preparation objects are finished and their state 
is OK. (Reported back with events from the preparation objects). 


Inputs 


— Conditions for execution of optimization (10 controller object attributes). Single 
connections. Three single connections are optional (for extensions of the plant). 


—  Sconnections (2 optional, spare for future use), one to each preparation object. 
Configured to Trigger back to the coordination object when preparation is done. 


— | connection to the optimizer object. Configured to Trigger back to the coordination 
object when optimization is done. 


— Results of optimization stored in local Basic Objects (3 input connections for each 
section, total of 15), single connections. 6 are optional (for extensions of the plant). 


Outputs 


— 5 output connections towards Preparation Object Types, 2 are optional (for 
extensions of the plant). 


— | output connection to the Optimization Object Type. 


— Results of optimization (3 output connections for each section, total of 15), object 
connections. 6 are optional (for extensions of the plant). 


Attributes 


—  TimeForLastOpt - The time for the last optimization is kept. Optimization may not 
run more often than every 30 minutes. 


Commands 
— None. All interaction with the operators is collected from the local Basic Objects 
Events 


- None. 
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Preparation Object Type, Three Instances 


° Function 


Calculates two prepared values from a number of measured inputs. Raises the event 
Preparation done to the Coordination Object Type when finished. Failure to read a 
value results in an error state. 


° Inputs 


Measured values from the Controllers, 32 single connections. 


° Outputs 


None 


° Attributes 


Results of the preparation (four floating points plus a status attribute) 
State: Successful or Reading of values failed 


Configurable attribute to “tune” the preparation with, default 100, configurable 
between 50.0 and 150.0 


Attribute containing section number | to 3 (up to 5 in an extension). 


° Commands 


Start preparation 


Modify tuning attribute. 


° Events 


Preparation is done. 


Optimization Object Type, One Instance 


° Function 


Uses the prepared values from each section and a number of configurable attributes to 
calculate an optimized production plan for each section. Also calculates the total 
material flow. Raises the event Optimization done when finished. Optimization is 
done with a third-party library, OPPIHOPP, which provides a C function interface to 
call from the User Object operation. 


° Inputs 


The prepared values from the preparation object instances. 5 input object 
connections, 2 optional. 


° Outputs 
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One output object connection for each result. The results are stored into local Basic 
Objects. 
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° Attributes 


— A few attributes for the tuning of the Optimization, configurable. 


— Results of optimization (18 floating points, three per section + three common which 
contain status information). 


° Command 
— Start Optimization. 
° Events 


— Optimization is finished. 


3.5.1.3 Data Base Design 
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A relational data base table is created when the object type attributes are designed. The object 
type name is part of the AdvaInform data base table name. The table is named 
userobjects.CO_ObjectTypeName_INST where ObjectTypeName is the name of the object 


type. 


NOTE 


To ease the access to your own instance tables, create a public symbol towards the 
instance table which is identical or similar to your Object Type Name. Your 
system manager can use the oracle user ocsmgr to create the symbol. 


Or, as an alternative, add the object type to AdvaInform SQL*Connect. The table 
name will then be equal to the object type name. 


Attributes are placed into the relational data base table in the order they are defined. 

A maximum of 254 attributes can be created. The object name is automatically created as a 
primary key. Please note that string lengths are decremented with one to compensate for the 
C syntax of the string length. See the following figure. 
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TdName: String [21]; 


Global data types ae . 
TdDescription: String [29]; 


/part (basic) /"Part Basic standard definition” 
Inherited attributes name: TdName/input /configure; 
description: TdDescription /input /configure; 
status: TdStatus; 


endPart 


/part (meanAttribute 


F ) 
User-defined loLim: Float [8,2] /configure; 

] 

] 


attributes hiLim: Float [8,2] /configure; 


value: Float [8,2]/output; 
endPart 


IMS data base column NAME VARCHAR(20) primary key 


definitions DESCRIPTION VARCHAR (28) 

name description status loLim hiLim value 
objxx1 Device 1 - -50.00 95.00 46.90 
objxx2 Device 2 - -60.00 95.00 47.65 
objxx3 Device 3 - -70.00 90.00 35.64 
objxx4 Device 4 - -60.00 90.00 37.21 
objxx5 Device 5 - -60.00 90.00 42.22 


Figure 3-4. Attribute definition resulting in IMS data base table columns 
Check the following before you specify the attributes: 


1. If you need to create reports or SQL*Form™ displays toward instances of the User Object 
type, put attributes in a logical order. 


2. Only attributes with the qualifier Configure are configurable, i.e., they can be given a 
value by the configuration tool. If you describe the attribute as input only, you can only 
modify it from the configuration tool not from within the object itself. 


3. Define the default value of the attribute when the object is created (if such a default is 
required). 
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4. If the configuration tool is going to check the entered configuration information, describe 
the constraints such as the range for the input or the available set of inputs. 


5. Are the number of attributes too large, i.e., will the corresponding instance table be too 
cumbersome to present and work with? 


6. Shall the automatic data base shadowing be turned off? If turned off, object instances with 
high frequent updates will generate a significantly lower cpu load. 


The OPPIHOPP example 


An evaluation of the demands on the User Objects (listed in Items 1-5 above) in the OPPIHOPP 
example follow: 


° In response to Item 1, it is not necessary to create reports on any of the specified User 
Objects. 


° In response to Items 2-5 above, the preparation and the optimization object types have 
configurable attributes. The attributes must be configurable, must have defaults, and must 
have configuration constraints. 


The number of attributes and input connections are limited for all User Objects and do not 
affect the design. 


3.5.1.4 Inheritance 


General 


A central function of Object Handling is the ability to inherit. Inheritance increases productivity 
and ease of maintenance and decreases errors. When an inherited function is corrected, the 
correction is carried out to the inheriting object types. If you find errors in copied software, you 
must correct it in each individual copy. 


Consider inheritance carefully before specifying your User Objects. You must decide on: 
° Which base to use for the inheritance (see Figure 3-4) 


° Inheritance between the application’s User Objects 


NOTE 


You must have a basic inheritance in the beginning of your inheritance chain. 
As default, the BasicObject is inherited. (Described below). 


The Basic inheritance 

The base consists of three ready-made object types: 

° A BasicObject, which has three defined attributes: name, description and status. 
° A DCSObject, which has one defined attribute: name. 


° A BlankObject, which does not include anything. 
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Inheriting the default, BasicObject, is recommended. BasicObject automatically provides 
powerful functions and three essential attributes that all object types should have. It also 
provides the ability to send event messages to the message log (if the AdvaInform History 
option is installed) and the Event and Alarm system. 


The DCSObject is primarily for ABB’s internal use. Object types from previous versions of 
ABB products are described using the DCSObject as a base. 


Using BlankObject as inheritance means to inherit nothing. An object that inherits nothing 
cannot be programmed using Object Type Builder. The only reason to use BlankObject is to 
describe a third-party object for the core system. 


The ready-made object types are abstract, which means that they can be inherited but not 
instantiated. 


As can be seen in Figure 3-4, objects that inherit the BasicObject inherit attributes, commands 
and event and alarm support. The difference towards objects inheriting the DCSObject is that 
they do not inherit any event and alarm support. From the BlankObject you can’t inherit 
anything. it is just the start of the chain. The figure also shows that inheritance can be done a 
several steps. 
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Figure 3-5. Inheritance Chain 


The BasicObject and the DCSObject do not include any connections. They support the 
following commands: 


Delete 
Deactivate 
Copy (name) 


NormalOperation. 


An additional command which is supported by the object handlers and not by the object itself 
also needs to be explained: 
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Activate (name). 
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Delete 


To remove the object instance, execute Delete. Delete deactivates the object before deleting 
itself. 


Deactivate 


To stop execution of the object, execute Deactivate. The object’s primary memory allocation is 
removed and it is no longer available in the run time environment. 


Copy (name) 


To create and name a copy of the object, execute Copy. Other than the name, the copied object’s 
attributes are identical to those of the object from which it is copied. 


NormalOperation 


To execute the object’s Normal Operation, request for NormalOperation. 


Activate (name) 


To start execution of the object, execute the Object Handler command Activate. The named 
object’s configured information is read, the object is initialized in primary memory and the 
object’s execution is started. 


See Appendix A - Syntax Description OTDL, for a complete description of the ready-made 
object types provided by Object Type Builder. 


Rules of Thumb for Using Inheritance 


° You must decide is if you want to inherit the BasicObject or the DCSObject. If you do not 
need to send messages to the message log or to the Event and Alarm subscribers and the 
status handling of the object is limited, select DCSObject. Otherwise, inherit the 
BasicObject, which is the recommended choice. 


° If your application applicable to many similar problems, you may want to define an 
abstract User Object which includes all common declarations, i.e., attributes, commands, 
events. Other User Object types then inherit this abstract object type and add only the parts 
specific to its solution. 


OPPIHOPP Example 


In the OPPIHOPP example, there are no specific demands on basic inheritance, so User Objects 
can use the default inheritance. There is nothing to gain on using inheritance in this example. 
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Inheritance Restrictions 
The following rules and restrictions regarding inheritance must be recognized: 


° Since Normal Operation is configurable, it is the only thing in an object type that cannot be 
inherited. There may be several Normal Operations defined for an object type, making it 
impossible to know which one is to be inherited. 


° You can add attributes, connections, commands and events to inherited functionality, 
but cannot delete or redefine! it. 


° Multiple inheritance, that is inheriting from two object types at the same time, is not 
supported. 


3.5.1.5 Using Third-Party Software (Libraries and Tools) 


During the analysis phase, you need to consider third-party libraries and tools. They are easy to 
call or activate from a User Object operation. Remember that libraries must be declared 
according to ANSI-C. 


In general, let the User Object: 

° take care of all interaction with the environment (inputs, outputs, commands) 

° provide the input to the third-party library through function or procedure calls 

° receive the output as return from procedure calls. 

Store the result in attributes or send with commands to other objects. See the example in Section 
1.8.4.4, Programming. 

OPPIHOPP Example 


In the OPPIHOPP example, the supplier of the optimization software provides a declaration file 
in ANSI-C and an object library. You need only enter this to the Object Type Builder. 


3.5.1.6 Implementation of Operations, “private functions” 
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An object’s behavior is primarily defined by its operations. The available operations, Normal 
Operations and Command Operations, are implemented in their own source files. 


You can implement several Normal Operations for each object type, but you can connect only 
one Normal Operation at a time to an object instance. You can design only one Command 
Operation for each object type and command. Command Operation is defined in the source file 
where the command is programmed. 


When you are implementing operations, are there constants, variables, small functions and 
procedures that should be common for the object type? If so, you can program and declare them 
in C++. Once you have programmed them, enter them into the ObjectBuilder so they can be 
used by all the object type’s operations. 


1. The data type definition of bitset32 and bitset16 data types is the only exception. New data bits may be 
added. 
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OPPIHOPP Example 


In this example, the Coordination Object Type saves the current system time when an 
optimization is done. Since you cannot send the result to the Controllers if more than 65 minutes 
have elapsed, the time is stored in a variable. This variable is local to the object type. Each 
object instance will get a copy of the variable which is accessible from all its operations. 


3.5.2 Implementation Steps 


Use the Object Type Builder to design object types off line. The normal procedure for each step 
is to edit one or several source files and then enter them into the ObjectBuilder tool for 
compilation or other processing. 


To design a new object type: 
1. Define the object type. 
a. Edit the OTDL file and design the different parts of the object type: 

- Give the object type a unique name and a description. 
- Define input and output attributes and connections for the new type. 
- Define the content of each subscription. 
- Define the commands to support. 
- Define the events. 


b. Compile the OTDL until it is error-free using the ObjectParser. Enter it to the 
ObjectBuilder and compile it, which results in: 


- The Object Type Description (the OTD) is created. 


- Source files for object-type-specific parts of the run time environment are 
created. 


2. Design Normal and Command Operations. This is the point where you do the 
programming according to the declarations made in the OTDL file. In this phase, you also 
use the ObjectBuilder to enter library declarations and declarations of routines written in 
other languages. 


a. Declare libraries and the other 3 GL routines (optional): 
- Edit the source files. 
- Enter them to the ObjectBuilder. 

b. Declare variables, constants and functions local to the object type (optional): 
- Edit the declaration files. 


- Enter the declarations to the ObjectBuilder. The local variables and functions can 
now be referred to by all the object type’s operations. 
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c. Create the operation source files for Normal and Command Operations. You must 
create at least one Normal Operation file. Repeat the following for each operation: 


- Edit the source file. 
- Compile until error-free using ObjectParser. 
- Enter it to the ObjectBuilder. 


This results in object libraries. Everything is now ready for you to the build the run 
time environment. 


3. Specify the run time environment for the new object type and build it. 


4. For each station the object type is to execute within or be referenced from, you must repeat 
the following steps: 


a. Create the type directory, rebuild the core system and restart the station. See Section 
3.7.4, Updating Object Type Directory 


b. Load the run time environment and start it for the nodes where the object type will 


execute. 
Q) 
Edit the OTDL: 
- Attributes 
- Connections 
- Subscriptions 
- Commands 
- Events 
Common 
OTD Source files i 
Declare libraries 
Program the External eh 
D) Operations Libraries 
( ) - Normal 
- Command 
(4) Compile Operation ate 
Library 
Specify the Run S 
3 Time Environment 
( ) and Build it 
v Run Time 
core system Environment 


Figure 3-6. Steps When Designing an Object Type 
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5. | Create instances and test the objects. See also Appendix I, Debugging of User Object 
Applications 


When you have saved the object type, but before you load it into an executable environment, 
you must make it visible to the rest of the automation system (Step 4 above). It will then be 
accessible through the core system and a description of it will be available to allow for example 
configuration of display elements. Section 1.8.3, Development of User Objects, gives a brief 
overview of the relationship between objects and the core system. 


3.5.3 Selecting method to read input connections 


The default method to read input connections keeps all references to the input objects between 
each execution of the object. This method is preferred because of its high performance. If you 
run out of memory on the RTA board, you can use another method. This method sets up all 
references, reads the data and then removes the references each time the object executes. 
Therefore it requires less memory. 


See Appendix D, ObjectUtil Commands for details on how to select read method. 


3.5.4 Load Balancing 


If many User Objects execute simultaneously the amount of data requests from them to the 
controllers may become too large resulting in overload situations and failure to read data 
properly. A load balance function is provided to prevent overloads. You can configure how 
many User Objects that may request for data simultaneously. 


See Appendix D, ObjectUtil Commands for details on how to tune the load balancing. 


3.5.5 EC library 


The application procedures for the EC library are described in Appendix G, External 
Communication Library. 


3.6 Accessing User API functions 


The User API library can be assigned to an Object Type as any external library. In general it is 
recommended to primarily use 


° the type directory functions 

° the demand subscriptions combined with the Do Request features 
° the execute operations functionality 

° the event subscriptions required for History access. 


In general Cyclic and other Event driven subscriptions than the History subscriptions may prove 
to be difficult to handle in combinations with ordinary User Object scheduling. 


See Appendix F, Object Type Examples for instructive examples. 
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3.7.1 Introduction 


Use the 3 tools, ObjectBuilder, ObjectParser and ObjectUtil to manage all the details of 
object design. Use the ObjectHandlers tool to transfer ready-made object handlers and object 
types to other IMS nodes. 


3.7.2 Starting the Object Type Builder and its tools 


You start the Object Type Builder from the AdvaBuild menu by selecting Object Type Builder, 
(see Section 2.4, Start-Up Procedures). As a result a Terminal window is started, see Figure 3-1 
in Section 3.3, Software Setup: 


From the Terminal window you can start the 4 Object Type Builder tools ObjectBuilder, 
ObjectParser, ObjectUtil and ObjectHandlers. 


The user interface is command-oriented, consisting of a number of commands which you enter 
to achieve requested actions. To activate the respective tool, in the terminal window, enter: 


ObjectBuilder, ObjectParser, ObjectUtil or ObjectHandlers. 


3.7.3 ObjectBuilder tool 


The ObjectBuilder tool consists of four main components where specific parts of the design are 
implemented. ObjectBuilder’s four main components are: 


° Object Type Definition: OTDLs are compiled to produce object types here. 


° Library Declaration: ObjectBuilder provides you the ability to use external libraries 
when you are programming operations for an object type here. 


° Operation Design: Command and Normal Operations are defined for an object type here. 


° Build: The execution environment (object handler) to handle the execution of object types 


’ 


OBJECTBUILDER 


is defined here 


TYPE 
DEFINITION 


LIBRARY OPERATION 
DECLARATION || DESIGN 


Figure 3-7. Structure of ObjectBuilder 
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It is not possible to do all operations in a sequence in the ObjectBuilder. When you have created 
the new object type definition and before you start its run time environment, you must make it 
available to the core system and its type directory. Do this as a separate action using a type 
directory utility which is started outside ObjectBuilder. See Section 3.7.4, Updating Object 
Type Directory. 


When the core system is re-linked and installed, you can start an object handler that includes the 
object type. 


3.7.3.1 Object Type Definition 
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Below follows an overview of each part of the ObjectBuilder tool. Each part is described with a 
graphical figure and with a short text introduction. By studying the figures, you will understand 
the ObjectBuilder command hierarchy. To get the detailed command syntax, see Appendix B, 
ObjectBuilder Commands. 


Use ObjectBuilder to design object types. The first step in defining the object type is using the 
Object Type Definition Language (OTDL). 


Text Editor 


Use any available text editor to create the source file, written in OTDL syntax, for the object 
design. 


Compiling the OTDL file 


When the OTDL is written or modified, the source file is compiled. There are two steps to 
compiling the OTDL file(s). The first step is to compile the file directly with the ObjectParser. 
Compile the OTDL file this way until it is error-free. When it is error free you enter it to the 
ObjectBuilder and compile it there. It is not until then that all the information about the object 
type is created. 


TYPE 
TYPE 
DEFINITION: DEFINITION 


objectTypeName 


— 


| | | Jee 


Compile 


Delete|| Assign | | Deassign Select 


Figure 3-8. Structure of Type Definition. 
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3.7.3.2 Library Declaration 


From the Normal and Command Operations, you can use external libraries and user-created 
routines written not only in C and C++, but also in FORTRAN and PASCAL 


You write your own declaration of the library routines in ANSI-C and store the declarations in a 
source file. Using ObjectBuilder, you can add and delete library declarations. Each declaration 
is given a unique alias when added. 


You must assign the library to the object type during type definition so that the operations can 
refer to the routines described in the library declaration. 


You can specify the linking order of the libraries by qualifying the Add with -first, - 
before=<aliasLibraryName> or -after=<aliasLibraryName>. 
Text Editor 


Create the source file for the library declaration in ANSI-C using an ordinary text editor. 
Any C++ manual describes how to implement these declarations. 


See Section 3.7.7, Programming the Operations, for general information on how to implement 
operations. If you prefer to write an operation in FORTRAN or PASCAL, do the following: 


° Write the PASCAL or FORTRAN routine and compile it until it is error-free. 


° Write a suitable declaration file in ANSI-C to describe the calling of the PASCAL or 
FORTRAN routine. 


° Declare the PASCAL or FORTRAN routine as an external library routine to 
ObjectBuilder using the Library declaration part. 


° Assign the library to the object type using the ASSIGN command in the type definition 
part of ObjectBuilder. 


° Call the PASCAL or FORTRAN routine(s) as you would any other routine in the operation 
code according to the defined C syntax. 


LIBRARY 
DECLARATION 


Command Overview 


Delete 
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Figure 3-9. Structure of Library Declaration 
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3.7.3.3 Operation Design 


The Normal and Command Operations contain the application code. They are programmed in a 
C++ (C). Routines written in the 3 GL languages FORTRAN and PASCAL can be used if they 
are properly declared in ANSI-C. 


You can design operations without entering the ObjectBuilder command hierarchy, just as you 
can compile the OTDL without entering the ObjectBuilder command hierarchy. Once you have 
edited the operation source file to a point where it can be compiled, use the ObjectParser to 
compile it. (See Appendix C, ObjectParser Commands for syntax.) 


This compilation includes the operation file and reports errors, if any exist. When the operation 
file is error-free, you can proceed by adding the operation file to ObjectBuilder. It does not need 
to be compiled again, it will be compiled when the run time environment is built. 


To create an effective implementation of more complex object types, you may need to define 
and implement variables, constants, and functions that can be referred to and used by all the 
object types’ operations. This is provided under User Definition in Operation Design 

(see Figure 3-10). 


Command Overview 


Y 


OPERATION OPERATION 

DESIGN: <— DESIGN 

objectTypeName 
NORMAL COMMAND USERDEF LASTOP F : F 
DESIGN: DESIGN: Recen: radia Select | List | |Help|| Exit | | Quit 
objectlypeName} | objectTypeName| objectTypeName | objectTypeName 


Figure 3-10. Structure of Operation Design 


3.7.3.4 Normal Design 


When the OTDL source file is compiled, preparation is made for the implementation of 1 to 10 
Normal Operations. You can write a source file consisting of the application code for each 
Normal Operation. 


Text Editor 


Create Normal Operation source files using any available text editor. 


3-40 3BSE 001 012R0501 


AdvaBuild® Object Type Builder User’s Guide 
Section 3.7.3 ObjectBuilder too! 


Command Overview 


NORMAL 


DESIGN: 
objectTypeName 


Figure 3-11. Structure of Command Design 


3.7.3.5 Command Design 


When the OTDL source file is compiled, source stubs for all commands are created. You can 
program each command without describing any declaration part. 


Text Editor 


Create the Command Operation source files using any available text editor. 


Command Overview 


COMMAND 
DESIGN: 
objectTypeName 


Figure 3-12. Structure of Command Design 
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3.7.3.6 Design of User-Defined Functions 


To create an effective implementation of more complex object types, you may need to define 
and implement variables, constants and functions that can be referred to and used by all the 
object type’s operations. For example: 


° When an attribute is required only for the coordination of the object’s operations, and it is 
not necessary to configure or present the attribute, you can describe it as a variable local to 
the object type but global between all the object type’s operations. 


° Describe constants that are of interest only for the object type operations. 
° Provide one or several functions that are used by several operations. 


User definitions are implemented in two files, a header file and an implementation file. 

Add those files to the object type using Object Builder (if no member functions are introduced, 
the implementation file can be omitted). The Object Builder then includes the header file in the 
private portion of the class declaration and the implementation file is compiled and later linked 
to the run time environment. 


Each object type is implemented as a C++ class. This class is generated from the object type 
definition. You can add user definitions such as type definitions, definition of members of basic 
C++ types, and define/implement member functions in the private portion of the class. All the 
C++ facilities can be used except attributes, which are const. This restriction is due to the way 
C++ handles const members. 


Due to C++ language limitations, constants are defined as an enum declaration. In the example 
below, the constant value BUFFERSIZE is given the value 100. 


enum dimensions {BUFFERSIZE=100}; 


When you implement the member functions, use the master file generated when the object type 
is compiled as the starting point for the implementation. This way the include directives needed 
to compile the file are present. Use ObjectBuilder’s GET command to fetch this file. (See the 
description of the command in Appendix B, ObjectBuilder Commands.) 


Write the member functions in the same way you write any member function in C++ when it is 
implemented in a file separate from the class declaration. For example, for the object type AI: 


something coAI::foo( { 
make something 


return something; 


} 


The class name consists of the prefix co and the object type name in lowercase letters. 


Text Editor 


Create the user-defined source files using any available text editor. 
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Command Overview 


USERDEF 
DESIGN: 
objectTypeName 


Figure 3-13. Structure of USERDEF Design 


3.7.3.7 Design of the Last Operation 


The Last Operation is an operation which is programmed in a similar way as Normal and 
Command operations. 


Text Editor 


Create the last operation source file using any available text editor. 


Command Overview 


LASTOP 
DESIGN: 


objectTypeName 


Figure 3-14. Structure of LastOperation Design 
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3.7.3.8 Build 


You can create the run time environment for the designed object types using ObjectBuilder. 
ObjectBuilder provides the facilities to specify and to build and install object handlers, which 
are what the run time environment consists of. Each object handler can handle from one to any! 
number of object types. An object type cannot be served by several object handlers in the same 
node. 


Adding and deleting an object type affects the instances of that object type as well as instances 
of all other object types belonging to that object handler as the object handler must be restarted. 
You must stop the existing object handler before you start a new version. At the same time, 

execution of object instances of the object types belonging to that object handler is interrupted. 


You can build object handlers for other nodes as long as those nodes have the same operating 
system, the same core system and the same type directory installed. For example, you can build 
object handlers for Advant Station 500 products with the same core system installed from an 
Advant Station 500 station. 


Environment variables can be defined for each individual object handler. This is done in the 
Environment Definition which is a sub mode to Build. You edit a file where You define the 
environment variables that shall be set for the Object Handler. For example: 


ABCDE=/tmp 
FGHI=xyz 


After editing, use add to store the definition. 


Command Overview 


BUILD: 
objectHandlerName 


<—__ 


Assign 


ssign 


Delete | | Environ Select 


Figure 3-15. Structure of Build Section 


1. “Any” means there are no theoretical limitations. You should, however, limit the number of object types to 15 -20. 
This will make packaging easier and resources allocated by the process will not reach critical limits. This is, of 
course, dependent on the size of the object types and the number of instances. 
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3.7.4 Updating Object Type Directory 


The type directory holds information on all object types known by the Advant OCS. When you 
define new object types via either the AdvaBuild Object Type Builder or the AdvaInform 
SQL*Connect Server, you need to update the applicable object type directories to make the new 
object types accessible. 


This procedure requires access at the ocsmgr user level. When adding a new object type via the 
AdvaInform SQL*Connect Server, update the Object Type Directory as follows: 


1. Open a terminal window. 

2. Source the IMS environment file. Note the blank character after the dot (“.”’). 
$. etc/IMSenvironment 

3. Change working directory to TypeDir/bin 
$ed ../TypeDir/bin 

4. Execute the tdgen script 
$ ./tdgen typedir/<typedir-—password> 


This is approximately 10 - 20 minutes. The script creates a new shared library that 
becomes the new Object Type directory. 


5. Open a second terminal window 
6. Log in as root from the second terminal window and stop IMS. 


See the Advant Station 500 Series IMS User’s Guide for information on how to stop IMS 
processes. 


7. Save the old shared library. Rename the new shared library from the first terminal window 
to the name of the shared library being used. 


$ ed ../1lib 

$ mv libtdTypeDirData.sl libtdTypeDirData.sl.old 

$ mv libtdTypeDirData.sl.new libtdTypeDirData.sl 
8. Start IMS from the second terminal window still logged in as root. 


See the Advant Station 500 Series IMS User’s Guide for information on how to re-start the 
IMS manually. 


When you are confident that the new type directory works correctly, delete the old one. 


3.7.5 Transferring Object Handler and Object Types to Other IMS Nodes 
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Follow these steps to transfer the object handlers you have developed with Object Type Builder 
into other Advant Stations 500 Series IMS. 


An Object Handler consists of an executable file and the definitions of the object types it can 
handle. Make sure that the target machine has the same Operating system and AdvaBuild and 
AdvalInform software version. Furthermore, its type directory must be updated with the object 
types that you install. 
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For the Advant Station 500 Series: 


Start the Object Builder terminal window. Change the default directory where there is 
write access and enough space (2M). Use the ObjectHandlers utility to do the transfer: 


$ObjectHandlers <ENTER> 
ObjectHandlers x.y-z> dump object_handler_name 


ObjectHandlers x.y-z> exit 


$ 

With this command you create the file <object_handler_name>TRANSFER .tar. 
As next step, use the utility ftp to copy the files to the target machine: 

S$ ftp <node_name or internet_address> 

Connected to node_name. 

220 node_name FTP server (Version - - ) ready. 

Name (node_name:user_name) : 

331 Password required for user_name. 

Password: 


230 User user_name logged in. 


Remote system type is UNIX. 
Using binary mode to transfer files. 


ftp> ed <to a directory on the target machine with write 
access to and enough free disk space> 


ftp> put object_handler_nameTRANSFER.tar 
ftp> bye 
22x Goodbye. 


Finally, use the ObjectHandler utility on the target machine to unpack it. After starting the 
Object Handler terminal window enter the following: 


$ ObjectHandlers <ENTER> 
Change the default directory to the directory You copied the file to. 
ObjectHandlers x.y-z> load object_handler_name 


ObjectHandlers x.y-z> exit 


3.7.6 Object Type Definition Language (OTDL) 
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The syntax and the terminology of OTDL is described in Appendix A, Syntax Description 
OTDL. The following sections will describe the different parts of the OTDL and will also give 
examples while the exact syntax is described in Appendix A. 
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This following section contains a description of the OTDL language and its features together 
with an example for each part. Read the examples and the tutorial in Section 3.4, Tutorial, 
before continuing with this section. The average object type described in Section 3.4.1, Average 
Example is used as example through all parts of the OTDL. 


An object type is defined by its: 

° Attributes 

° Connections (input and output to other objects) 
° Commands 

° Events. 


When any of these are redefined, the object type is redefined. This is not possible to do if 
instances of the object type exist. 


The application code of the object type is described in two blocks: 
° Normal Operation (algorithm) (compulsory to create) 
° Command Operation. 


Every object type can have from | to 10 Normal Operations defined. Only one can be used in 
each object instance. You must create at least one Normal Operation. You cannot create any 
instances before a Normal Operation exists. 


You can create new object types that inherit an existing object type. This is thoroughly described 
in Section 3.5.1.4, Inheritance. 


An object type definition is defined by its sub definitions, which consist of: 
° Object type header 

° Local data type definitions 

° Global data type definitions 

° Part (basic) 

° Basic attributes 

° Part (UserDefinedParts) 

° Attributes 

° Connections 

° Subscriptions (Composite attributes) 
° Commands 


° Events. 
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Example: 


Object type header __ p> average/descr(” Average 


calculation’’) 


/typeDef 
Local data type TdStatus: Bitset32 ( 
definition loLimError: Bit(8); 
hiLimError: Bit(9)j; 
unAcknowledged: Bit(10);); 
endTypeDef 
Dave declacation /part (averageAttribute) /descr(”Average attr’s and conn’s”) 
loLim: Float[8,3] /default (20.0) /configure/range (- 
10.0:300.0); 
Aes > hiLim: Float [8,3] 
/default (90.0) /configure/range(50.0:500.0); 
value: Float [8,3] /default (60.0); 
: LimTR: IntShort/input /default(3) /configure /range(1:300); 
a obj1: connect Float [8,3] /input; 
obj2: connect Float [8,3] /input; 
obj3: connect Float [8,3] /input; 
/part (optConnections) /descr(“Optional single float conn’s”) 
optObj1: connect Float [8,3] /input/optional; 
optObj2: connect Float [8,3] /input/optional; 
optOb 33: connect Float [8,3] /input/optional; 
endPart 
/subscription 
Subscription —___> avrgCyclic: (value, status); 
definition ou 

endSubscription/ 

/command 
Command changeLimit: (IntLong /input limitLoHi, 
definition Float [8,2] /input newLimit); 

ACKNOWLEDGE (IntSmall /input opCode, .... (Master specific) 
IntLong /input dValue); 

endCommand 

/event 

/* Events */ 
eventHiLim() ; 
eventLoLim() ; 

Event — eventAnyLim() ; 
Definitions 
endEvent 
end 
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Certain parts of the object type definition are mandatory and must be defined. There are also a 
number of supplementary parameters which can be omitted if not applicable. 


3.7.6.1 Object Type Header 


NOTE 


All identifiers given in the OTDL are stored with case-sensitivity. Checks for 

uniqueness, however, are made without regard for case, that is, they are case- 

insensitive. This is to ensure user interaction, except programming, where, for 
example, object names or attribute names are typed in, “forgiving.” 


When you refer to object type names, command names and so on when you work 
with the ObjectBuilder, ObjectParser, ObjectUtil or ObjectHandlers tools all 
your references can be made case insensitive. Capital or lowercase letters at your 
choice. During the programming however, you must refer to all variables case 
sensitive as the nature of the C++/C languages are case sensitive. 


The object type header defines general object type parameters. A header definition consists of 
the following mandatory and supplementary parameters. 


° General mandatory parameters: 


Object type name. The object type name identifier must be a unique object type 
name for the system configuration. ObjectBuilder ensures that it is unique. 


° General supplementary parameters: 


Object type description. Optional, contains a short object type description. 


Object type inheritance. The inherited object type must exist. Parts, attributes, 
connections, subscriptions, commands and events are inherited and added to the new 
object type definition, as if they belonged to it. With one exception, inherited 
information cannot be deleted or modified. The exception is that free bits of the bitset 
data types (Bitset16 and Bitset32) can be defined. 


Abstract object types. Use abstract object types to group common attributes, 
Command Operations, subscriptions and events for several object types. Abstract 
object types cannot be configured to object instances and can only be inherited into 
other object types. 


Configuration tool name. Name the configuration tool. The Object Configuration 
tool is specified by giving the abbreviation coct (COmmon Configuration Tool). 
For object types not completely implemented using the Object Type Builder, no tool 
shall be given (default). 


Example 


average /descr ("Average calculation”) /tool(coct) 


object type definition 


end 
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3.7.6.2 Local Data Type Definitions 
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Define new local data types, based upon the data types described in Table 3-2. 
You can define the following local data types: 

° Open Arrays 

° Structs 

° Arrays 

° Unions 

° Enums 

° ShortEnums 


° Bitset32 and Bitset16. 


NOTE 


A number of data types are not fully supported by the ObjectBuilder. They can be 
used to describe other objects using the ObjectParser utility. Objects built with the 
ObjectBuilder cannot use these data types. This applies to all of the above listed 
data types except Bitset16/32. 


You can also define a local data type that can be used within an object type, i.e., floating points 
of a certain size and precision or a frequently used string size. See the examples of local data 
type definitions below. 


There are a number of global data types included in the Object Type Builder distribution. 
Since these grow continuously, the best way to examine existing global data types is to use the 
ObjectUtil utility. (See Appendix A, Syntax Description OTDL.) At a minimum, the global 
data types TdName, TdDescription and TdStatus are always available. Global data types can 
be used as any other data type. 


Bitset Type Definitions, Status Attributes 


Bits are collected together in Bitset32 or Bitset16 “containers.” The bit positions in those 
containers are described in a local type definition. 


A Bitset definition has its own set of mandatory and supplementary parameters as follows. 
° General mandatory parameters: 


— Collecting Bitset type definition name. The type definition name may be the name 
of an inherited Bitset type definition. 


- Bit name. The user-defined bitName must be unique for the bitset definition, 
including inherited bits. 


—  Bitset position. The position in the referenced Bitset array. 
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Status Attributes 


Boolean variables, grouped together to a 32/16 bit bitstring, are the most common way to report 
an object’s status. Boolean variables give complete information about the object’s status. 

The status bits are described in the OTDL with the data type definition Bitset. They are collected 
into attributes using those local data type definitions. 


Most object types have a status attribute. This attribute is inherited either from a user-defined 
object type or from the default inheritance (BasicObject). 


POSITION 

1 pd 3 4 5 6 32 
Yr. Y ' Y Y Y 
aeive error updated selected manual blocked 


STATUS 


Figure 3-16. Status Attribute 


The status attribute inherited from the BasicObject has the following Bits defined in the local 
Bitset32 data type TdStatus: 


Table 3-1. Bits in TDStatus 


Name Position Explanation 
active 1 Object active i.e. ready to run 
error 2 Indicates the overview status of the object. 
updated 3 Indicates if the object has been updated since 
object execution started. 


The rest of the status bits are free to be defined as part of the object type design. 
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Examples of Local Data Type Declarations 
average /descr ("Average calculation”) 
/typeDef 

TdStatus: Bitset32 ( 


loLimError: Bit(8); 


hiLimError: Bit (9); 


unAcknowledged: Bit(10);); 


arrayOfBytes: openArray IntShort (50); 


structExample: struct ( 
systemTime: String[21]; 
entryValue: Float[8,2]; 
entryStatus: IntSmall; 
objectStatus: IntSmall;); 
myFloatType: Float[8,2]; 


endTypeDef 
NOTE 
A blank type definition, that is with only /typedef and endTypeDef, is not 
allowed. 


3.7.6.3 Parts 


Collect attributes and connections in parts to structure the configuration display, i-e., all 
attributes regarding event and alarm handling. An object type definition can contain an 
unlimited! number of part definitions. Part contents are user-configurable, but there are some 
restrictions: 


° An object type definition must contain a basic part. This part is inherited from one of the 
basic objects described in Appendix G, Syntax Description OTDL. 


° You cannot add attributes nor merge other parts into inherited parts. 
A part definition consists of the following mandatory and supplementary parameters. 
° General mandatory parameters: 


— Part name. A part name must be unique for the object type definition, including the 
inherited parts. 


° General supplementary parameters: 
— Part description. A part descriptions contains a short description. 


—  Attribute/Connection definitions. An unlimited! number of attribute and/or 
connection definitions. 


1. See Section 3.2, Capacity and Performance 
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Example 
average /descr ("Average calculation”) 
/part (meanAttribute) /descr (“Average attr’s and conn’s”) 
part information 
endPart 


end 


An object type definition can contain a number of parts, each having a number of! attribute 
definitions. 


° General mandatory parameters: 

— Attribute name. Attribute name unique within the object type definition. 

— Data type. See the description below for each of the data types and Table 3-2. 
° General supplementary parameters: 


— Direction. The default direction is bidirect. If the access to the attribute is limited, 
you can request the direction input. See the explanation of direction below. 


— Configuration parameters. Help information for the configuration tools such as 
allowed configuration values (see below). 


° Input attribute(s), supplementary part: 
— Default. A default value assigned at instance creation (can be altered at 
configuration). 
Direction 
As default, the attributes have the direction bidirectional, which means: 
° They can be assigned a value during object type design as well as during configuration. 
° They can be modified from within the objects, i.e., from the operations. 
An attribute with the direction input has limited access—only the first part is allowed: 


° Values can be assigned during design and configuration, but not from the operations. 


1. The number of attributes is limited to 254. 
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Configuration Information Supplied for Attributes 


You can also specify configuration constraints and storage formats during object type design, 
giving the following information. 


° Display length/data base size and number of decimals. Qualifiers for Float and Double 
data types that specify the data base storage length and precision. 


° Configuration constraints for attributes. They may be given as decimal, hexadecimal or 
octal values. 


= A set of allowed values, for example, 2, 4, 6, 8 
OR 
— A range the value must fall within, for example, 32-45. 


See Table 3-2 for a listing of valid constraints for different data types. 


NOTE 


Many data types have default constraints. An IntSmall and an IntShort have upper 
and lower limits which can never be passed. 
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Below, all the data types supported for User Object attributes are shown in Table 3-2. 


Table 3-2. Supported data types for User Object attributes. Their restrictions. 


Name Size Betault Range ek Comment 
allowed | support | support 

IntSmall 8 bits yes yes yes If no range or set is given fora 
configurable attribute, a default 
range according to the limits for the 
data types size is set. 

IntShort 16 bits yes yes yes See comment for IntSmall 

IntLong 32 bits yes yes yes See comment for IntSmall 

UlIntSmall | 8 bits yes yes yes See comment for IntSmall 

UlIntShort | 16 bits yes yes yes See comment for IntSmall 

UIntLong 32 bits yes yes yes See comment for IntSmall 

Float 32 bits yes yes yes Length and no of decimals required, 
default 8,2 

Double 64 bits yes yes yes Length and no of decimals required, 
default 8,2 

String(n) max 256 yes no yes Always complemented with a string 

char length value which shall be in C 

syntax i.e with an extra byte for 
terminator. Default value is limited to 
40 characters. 

Boolean 8 bits yes no no true, false, set or reset 

Bitset32 32 bits yes yes yes 

Bitset16 16 bits yes yes yes 


Object Type Builder provide you with the ability to define Object Types for the Advant OCS. 
These Object Types are not implemented as User Objects. Existing object types in the Advant 
Controllers as well as some System Objects within IMS are examples of object types which are 
described in that way. For such object types, additional attribute data types can be described. 
See below. To create such an Object Type you use the ObjectParser utility with the qualifier - 
mode=extparse. See Appendix C, ObjectParser Commands. 
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To create such an Object Type Description you simply follow Step | and 4 in Section 3.5.2, 
Implementation Steps and use the right ObjectParser qualifier. 


Table 3-3. Supported data types for attributes of other Object Types. 


: Default Range Set 
Name Size Comment 
allowed support support 
struct free no no no 
Open array free no no no 
Array free no no no 
Union free no no no 
Enum free no no no 
Short Enum free no no no 
Char 8 bits yes yes yes See comment for IntS- 
mall in Table 3-2 


Example of Attributes 


average /descr ("Average calculation”) 


/typeDef 


TdStatus: 
loLimError: 
hiLimError: 


endTypeDef 


Bitset32 ( 
Bit (8) ; 


Bit(9);); 


/part (averageAttribute) /descr(“Attributes for result and limits”) 


loLim: Float[8,3] /default (20.0) /configure/range (-10.0:300.0) ; 


hiLim: Float[8,3] /default (90.0) /configure/range (50.0:500.0); 


value: Float[8,3] /default (60.0); 


LimTR: 


endPart 


end 


IntShort/input /default (3 


configure 


range (1: 300); 
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Example of Attributes of Locally Defined Data Types 


InterestingType /descr ("Example of local data types”) 
/typeDef 
TdStatus: Bitset32 ( 


loLimError: Bit (8); 


hiLimError: Bit (9); 
unAcknowledged: Bit(10);); 
structType: Struct ( 
strFloat: Float [8,2]; 
strLong: intLong; 
strName: TdName; 
strStatus: TdStatus;); 
unionType: Union ( 
unionFloat: Float [8,2]; 
unionLong: intLong; 
unionName: TdName; 
unionStatus: TdStatus;); 


arrayType: Array structAttr[4]; 


openArrayType: openArray unionAttr[60000]; 


englishNoType: Enum (one:1; two: 2; three: 3;); 


spanishNoType: shortEnum (uno: 1; dos:2; tres: 3;); 


endTypeDef 
/part (FunnyAttributes) /descr(“Funny attributes”) 
SEYUCEALEr? structType; 


unionAttr: unionType; 


arrayAttr: arrayType; 
openArrayAttr: openArrayType; 


enumAttr: englishNoType; 


shortEnumAttr: spanishNoType; 
endPart 


end 
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Example of Default, Range and Set Usage 
// Object: RangeSet 


RangeSet /descr(“Example of range,set,default”) 
// 
/part (DefaultRange) 


DefRangeIntSmall: IntSmall /input /default(12) /configure; 
DefRangeIntShort: IntShort /input /default(22) /configure; 
DefRangeIntLong: IntLong/input /default (32) /configure; 


DefRangeFloat: Float [8,2] /input /default (43.20) /configure; 


DefRangeDouble: Double [8,1]/input/default (54.4) /configure; 


DefRangeString: String [40]/input/default (“Default 
text”) /configure; 


DefRangeBoolean: Boolean /input /default (true) /configure; 


endPart 


/part (Range) 
RangeIntSmall:IntSmall/input/default (11) /configure/range (10:20); 


RangeIntShort: IntShort /input /default (39) /configure 
range (20:40); 


ua 


RangeIntLong: IntLong/input /default (49) /configure /range (30:60); 


RangeFloat: Float [8,2]/input 
/default (69.0) /configure/range (10.0:90.0); 


RangeDouble: Double [8,4] /input /default (99.9) /configure 
/range(10.0:200.0); 


endPart 


/part (Sets) 


SetIntSmall: IntSmall /input /default(10) /configure 
/set (10,12,20); 


SetIntShort: IntShort /input /default (22) /configure 
/set (20,22,40); 


SetIntLong: IntLong /input /default (60) /configure /set (30,32,60); 
endPart 


end 
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3.7.6.5 Connections 


An object type definition may contain a set of parts, each with a number of connection 
definitions. The input connections can be: 


° Single connections. Connections to one (ordinary) attribute from another object. 
° Object connections. Connection to a number of attributes from another object. 
The output connections are more restricted: 


° Object connections. The definition of output object connections is needed for the 
syntactical check of the commands toward them. 


The name of a selected object that matches the connection is given during configuration. 


Mandatory and Supplementary Parameters of Connection Design 
For all object connections, a number of common parameters are described: 
° General mandatory parameters: 


— Connection name. The connection name must be unique for this object type 
definition, including inherited connection and attribute names. 


— The data type. See the description below for each of the connection types. 
— Direction. Identifies the connection as input or output. 
° General supplementary parameters: 


— Optional. Identifies the object connection as optional, i.e., not needed for all 
instances of the object type. If not connected during configuration, the connection 
cannot be used from any of the operations. 


— Suppression. See Suppress below. 
— Default value (not allowed for optional connections). 
° Input Connection(s), supplementary part: 


— Trigger. (Object connections only.) Identifies whether events from the input object 
connection shall trigger the execution of the objects Normal Operation. The event to 
subscribe upon is given. When an object instance is started, it submits a subscript 
request to the object configured to the input connection. See the examples below. 


— Trigger Exclusive. Has the functionary as a normal triggered connection, except that 
the object does not read any other triggered connection when this type of connection 
has triggered. 
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Suppress error actions 


Error handling during Normal Operation execution is monitored by the supplementary 
parameter suppress. 


Before the operation is executed, all connections are read and checked. If the reading fails and 
the connection is not suppressed, the following actions are taken: 


° Execution of Normal Operation is disabled. 
° Object status is set to error. 
If the reading fails and the connection is suppressed: 


° The execution of the operation is not disturbed. The operation code decides what to do if 
the reading fails. 


The suppress feature lets the operation designer take special actions when errors are recognized. 
The object continues to execute unless the operation code deactivates it. Bidirectional attributes 
can be set to suitable error values or set to perform other appropriate actions. Events can also be 
sent within the operation, provided that the BasicObject is inherited by the object. 


Use of suppress error actions from the object operations is described in Section 3.7.7.5, Details. 
For more information about run time execution of objects, see Section 1.8.4.7, Run Time 
Environment. 


Single Connections 


A single connection describes a single value that can be read. The connection can be configured 
toward an object attribute or a constant value. 


° General mandatory parameters: 

— Connection name 

— Data type (format types such as Float, IntLong, etc.) 
° General supplementary parameters: 

— Optional 

— Suppression 


- Default. 


(— > 


: Name General mandatory 
Single Connect. | pata type parameters 
INPUT 

Optional General 
Suppression supplementary 
Default parameters 


NS J 


Figure 3-17. Design Information for a Single Connection 
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Object Connections 

Object connections are separated into two groups: 
° Input connections 

° Output connections. ! 

The following information can be entered during object design. 
° General mandatory parameters: 


- Connection name 


— Name of an object type. (See Object Types Supported as Connections, which 
follows.) 


— Direction. The direction must be defined either to input or to output. 
° General supplementary parameters: 

— Optional. 
° Input connection(s), supplementary parameters: 

— Suppression 


— Trigger on a specified event of the referenced object type. 


— Subscript (composite attribute) of the referenced object type. The name of a 
composite attribute. The composite attribute contains a list of attributes of the 
connected object. By referring to the composite attribute name, all attributes included 
in the composite attribute are automatically read. 


aS Output oe si 


Maele Name General object Name General 
Connect Object type ianealery. connection | Object type mandatory 
4 Direction R Direction pelaneter 
Optional — General Optional supplementary 
Suppression supplementary parameter 
Trigger parameter 
Subscription 
(Attr. list) 


= er, ‘ wy 


Figure 3-18. Design Information for Object Connections 


Object Types Supported as Connections 


You can make a connection to any of the object types below: 
° Object types supplied by ABB 

° Application object types 

° Abstract object types. 


1. Please note that an output connection only describes what object type an output connection has. The syntax of 
commands given to the connection can be checked. 
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Use abstract object types to group common attributes, command operations, subscriptions and 
events for several object types. These abstract object types cannot be configured to object 
instances. Abstract object types can only be inherited to other object types. 


Visible attributes 


name 
description 


Alabstract 


status Defined 
value 
Inherits Inherits Visible attributes 


name 


description . 
status Inherited 
value 

hiLim1 

lok lin Defined 


Figure 3-19. Inheritance of Abstract AI Type to Three Different AI Object Types 


Abstract object types make it possible to implement more general objects. If you use the 
abstract AI type when defining a connection, the application is independent of the type of AI 
used for, for example, certain transducers. 


Using abstract input object connections restricts access to a set of attributes for abstract object 
types. In the previous example, the following attributes are common: 


° Name 
° Description 
° Status 


° Value. 


Using Single Connections or Object Connections 


Each input and output connection describes a specific piece of information to be read by or 
written to the object. If you specify an object connection during object type design, the 
operation programmer has a higher degree of functionality than if a single connection is used. 
Specific connection description during object type design leads to increased functionality for the 
connection from the operation. On the other hand, specific description of the connection will 
limit possible configurations. 


The following functions are available for object connection from the operations: 


° You can address all specified attributes as listed, including the status bits (if status is 
included—this is strongly recommended). 


° You can use the object commands (if output). 


In addition, all access to the different object types is already type controlled at compilation time. 


3BSE 001 012R0501 


AdvaBuild® Object Type Builder User’s Guide 
Section 3.7.6 Object Type Definition Language (OTDL) 


Abstract object connections are different in that all object types inheriting the abstract type can 
be connected. Accessible attributes are limited to those defined by the abstract type. 


For a single connection, only the specified attribute (typically value) is accessible from the 
operation. No status check can be made. Output is not possible. 


NOTE 


Object connections use Composite attribute definitions (subscriptions) as 
reference to the list of attributes to fetch. MOD 300 Process Objects have no 
composite attribute definitions so you can‘t use object connections towards them. 


Example: average and averageObj object types 


average 


The average object type has defined it is input to consist of floating point attributes. During 
configuration any object attribute of the data type float of any object instance can be configured 
as input. 
Underlined information is valid only for Master. 
average /descr (“Average value”) /tool (coct) 
/typeDef 

TdStatus: Bitset32 ( 


loLimError: Bit(8); 


hiLimError: Bit (9); 


unAcknowledged: Bit (13);); 


endTypeDef 


/part (averageAttribute) /descr(“Attributes for result and limits”) 
loLim: Float[8,3] /default (20.0) /configure/range (-10.0:300.0); 
hiLim: Float[8,3] /default (90.0) /configure/range (50.0:500.0); 
value: Float[8,3] /default (60.0); 


LimTR: IntShort/input /default(3) /configure /range(1:300); 


endPart 

/part (compConnections) /descr(“Compulsory single float conn’s”) 
obj1: connect Float [8,3] /input; 
obj2: connect Float [8,3] /input; 
obj3: connect Float [8,3] /input; 

endPart 

/part (optConnections) /descr(“Optional single float conn’s”) 
optObj1: connect Float [8,3] /input/optional; 
optObj2: connect Float [8,3] /input/optional; 
optObj3: connect Float [8,3] /input/optional; 

endPart 


end 
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averageObj (Master specific) 


The averageObj object type will always be configured against input objects of the type AI. 
The available attributes as described by the subscription definition ain_ab1_dcx are, for 
example, VALUE and STATUS. 


averageObj /de 
/typeDef 
TdStatus: 


loLimE 


hiLimE 
unAckn 
endTypeDef 

/part (mea 

lo 

/defau 

hi 

/defau 


val 


sigs 
endPart 


scr(“Average of 3 to 4 AI values”) 


Bitset32 ( 

rror: Bit(8); 

rror: Bit(9); 
owledged: Bit(10);); 


nAttribute) /descr(“Attributes for result and limits”) 


Lim: Float [8,3]/input 
1t (20.0) /configure/range=(-10.0:300.0); 
Lim: Float [8,3]/input 
1t (90.0) /configure/range=(50.0:500.0); 
ue: Float[8,3]/default (60.0); 
mTr: IntShort/input /default (3) /configure /range(1:300); 


/part (Connections) /descr (“Connections”) 


Obj1: connect AI (ain_ab1_dcx) /input; 


Obj2: connect AI (ain_ab1_dcx) /input; 


Obj3: connect AI (ain_ab1_dcx) /input; 


optObj: connect AI (ain_ab1_dcx) /input/optional; 
endPart 
/subscription 
avrgOCyclic: (value,status) ; 
endSubscription 
/command 
changeLimit: (IntLong /input limitLoHi, Float [8,2] 


/inputnewLimit) ; 


dummy : 
ORDER 
/input 
dialog 

dva 


ACKNOW. 


(); 

(IntSmall /input opCode, IntShort /input opProp, IntSmall 
typeOfReq, Boolean /input eventLog, IntLong /input 
Id, Float [8,2] /input aValue,IntLong, /input 

lue, IntSmall /output status,IntShort /output textIndex); 


LEDGE (IntSmall /input opCode, IntShort /input opProp, 


IntSmall /input typeOfReq, Boolean /input eventLog, 


IntL 
/input 


ong /bidirect Id, Float [8,2] /input aValue, IntLong 
dValue, IntSmall /output status, IntShort /output 


textIndex) ; 


endCommand 


end 
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If another object type wants the averageObj object as input it would write an object connection 
towards the averageObj composite attribute avrgOCyclic: 


optObj1: connect averageObj (avrgOCyclic) /input; 


3.7.6.6 Subscriptions (Composite attributes) 


Composite attributes contain a list of attributes which can be referred to as one entity using the 
subscription definition. See the following example, where the composite attribute avrgCyclic 
contains the attributes value and status. User-defined composite attributes are added to the 
inherited composite attributes. 


NOTE 


The term subscription is kept for backward compatibility. The appropriate term is 
Composite Attribute. Do not mix this with the functionality subscribe which is the 
functionality used to read attributes (including composite attributes) through the 
core system. 


Example 
average /descr ("Average calculation”) 
/typeDef 

TdStatus: Bitset32 ( 


loLimError: Bit(8); 


hiLimError: Bit (9); 
unAcknowledged: Bit(13);); 
endTypeDef 


/part (averageAttribute) /descr(“Attributes for result and limits”) 
loLim: Float[8,3] /default (20.0) /configure/range(-10.0:300.0); 
value: Float [8,3]; 


optOb 33: connect Float [8,3] /input/optional; 
endPart 


/subscription 


avrgCyclic: (value, status) ; 


endSubscription 


end 


Other object types that want to refer to the average object type as input connection do this with 
a connection definition: 


averagevaluel: connect average (avrgCyclic) /input; 


3BSE 001 012R0501 3-65 


AdvaBuild® Object Type Builder User’s Guide 
Chapter 3 Configuration and Application Building 


3.7.6.7 Commands 


3-66 


You can define commands as part of the object type definition. The command list is a syntax 
description of available commands that can be given the object type. The list contains the name 
of each command and a syntax description for the command’s parameters. See the example 
below. 


Command names and their semantics must be unique in the system. The syntax, i.e., the 
parameter’s data types, may differ. This is checked when the object type definition is compiled. 
For example, the set value of an object type has data value as a Float data type, but another 
object type has a Boolean or enumerated data type: 


setValue (Float: newValue); Type one 
setValue (Boolean: newValue); Type two 


This way, the command setValue is available for both object types. The only difference is the 
format of the new value. 


If the definitions of the setValue commands as described exist, the following command 
definition will not be accepted as it has more parameters: 


setValue (Boolean: newValue, Float: newValue); 


You must always define two Master specific commands, order and ACKNOWLEDGE, if the 
object type is to generate alarms. These commands support interaction with the alarm lists when 
alarms are generated and acknowledged. The declaration of the commands is described in the 
example below. Their implementation is described in Section 3.7.7.5, Details. There is no 
equivalent function in Object Type Builder MOD 300. 


Example of Changelimit, ORDER and ACKNOWLEDGE Commands 


average /descr ("Average calculation”) 
/typeDef 
TdStatus: Bitset32 ( 


loLimError: Bit(8); 


hiLimError: Bit (9); 
unAcknowledged: Bit(13);); 

endTypeDef 

/part (averageAttribute) /descr(“Attributes for result and limits”) 
loLim: Float[8,3] /default (20.0) /configure/range (-10.0:300.0); 
value: Float [8,3]; 


optOb 33: connect Float [8,3] /input/optional; 
endPart 
/subscription 

avrgCyclic: (value,status); 


endSubscription 
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/command 
changeLimit: (IntLong /input limitLoHi, Float [8,2] /input 


newLimit) ; 


dummy : () ; 

ORDER (IntSmall /input opCode, IntShort /input opProp, IntSmall 
/input typeOfReq, Boolean /input eventLog,IntLong /bidirect 
dialogId, Float [8,2] aValue,IntLong, /input dvalue, IntSmall 
/output status,IntShort /output textIndex) ; 

ACKNOWLEDGE (IntSmall /input opCode, IntShort /input opProp, 


IntSmall /input typeOfReq, Boolean /input eventLog, IntLong 
/bidirect Id, Float [8,2] /input aValue, IntLong /input 
dValue, IntSmall /output status IntShort /output textIndex) ; 


endCommand 


end 


3.7.6.8 Object Events 


Events are described in a format similar to commands. A unique event name is followed by a list 
of parameters (data types). See the example below. User-defined events are merged together 
with the inherited events. 


Event declarations serve the purpose to declare the events that can trigger other objects. 


The event can be declared with or without parameters. It can only be used for trigger purposes. 
The trigger function is available for object connections. 


The following figure explains triggering: 


7 MrX =X 


Object instance of x-type. It has an 
input connection towards the 
average type with the attributes 
described by the avrgCyclic 
composite attribute. It is configured 
to be triggered by the event 
eventAnyLim. 


value and status 
transferred when 
eventAnyLimit 
is raised 


Mean 
When eventAnyLim is raised in 
Object instance of average. the Average object the MrX object is 
When any alarm limit is started with the attributes described 
exceeded it raises the event by avrgCyclic, that is status and 
eventAnyLim. \_ value, returned. 


Figure 3-20. Triggering when an event is raised 


A subscription is defined to each connection. That subscription is received as input to the object 
requesting triggering, when a trigger occurs. 
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It is up to the application developer to specify when an event is to be raised. Typical examples of 
events that another object triggers upon may be: 


° The value has changed (typical for digital value objects). 
° An alarm limit has been transgressed. 
° The object has gone into an alarm state 


° The object leaves an alarm state. 


Example of Object Definition Events 
average /descr ("Average calculation”) 
/typeDef 

TdStatus: Bitset32 ( 


loLimError: Bit(8); 


hiLimError: Bit (9); 


unAcknowledged: Bit(10);); 


endTypeDef 

/part (averageAttribute) /descr(“Attributes for result and limits”) 
loLim: Float[8,3] /default (20.0) /configure/range (-10.0:300.0); 
value: Float [8,3]; 


optOb 33: connect Float [8,3] /input/optional; 
endPart 
/subscription 
avrgCyclic: (value, status); 
endSubscription 
/command 


changeLimit: (IntLong /input limitLoHi, Float [8,2] /input 
newLimit) ; 


order (IntSmall /input opCode, IntShort /input opProp, IntSmall 
/input typeOfReq, Boolean /input eventLog,IntLong /bidirect 
dialogiId, Float [8,2] aValue,IntLong, /input dvalue, IntSmall 
/output status,IntShort /output textIndex) ; 


ACKNOWLEDGE (IntSmall /input opCode, IntShort /input opProp, 


IntSmall /input typeOfReq, Boolean /input eventLog, IntLong 
/bidirect Id, Float [8,2] /input aValue, IntLong /input 
dValue, IntSmall /output status, IntShort /output textIndex) ; 


endCommand 

/event 
eventHiLim() ; 
eventLoLim() ; 
eventAnyLim () ; 

endEvent 


end 
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3.7.6.9 Comments 


General comments are allowed anywhere between the sub definitions, but not in the sub 
definitions. Line comments and block comments are supported. See the example below. 


Example, Object Definition Comments 
average /descr ("Average calculation”) 
/typeDef 

// This is a line comment. 


TdStatus: Bitset32 ( 


loLimError: Bit (8); 


endTypeDef 

/part (averageAttribute) /descr(“Attributes for result and limits”) 
loLim: Float[8,3] /default (20.0) /configure/range(-10.0:300.0); 
value: Float [8,3]; 


optObj3: connect Float [8,3] /input/optional; 
endPart/* This 
isa 


block comment. */ 


NOTE 


* is not a valid character within a block comment. 


3.7.6.10 Global Data Types 


Global data type definitions are, as the object type definition, described with the OTDL. Global 
data types are stored in the object type definition data base and are used when all OTDL files are 
compiled. 


NOTE 


An OTDL file with global data type definitions may not contain any object type 
definition. In addition, it must be compiled with the ObjectParser utility using the 
qualifier -TYPE. 
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Example, Global Data Type Definitions 


BasicHistoryObject /descr(“Basic History Object”)/Inherit (BlankObject) 
|| ------------------------------ TYPEDEF ---------------------------- 


/globaldef 


// Definition for Name used in the API 


NameType: String[36]; 


// Definition of Object name and attribute 


AccessType: Struct (objectName: NameType; attributeName: 
NameType;); 


// Definition of Array of Log Names 


LogNames: openArray NameType[1000]; 


// ObjectID definition 
ObjectID: struct (highLong: UIntLong; lowLong: UIntlLong;); 


// Definition of the Time Stamp for history 


TimeStamp: Struct (seconds: UIntLong; microSeconds: UIntLong;); 


// Definition of the Time Interval for history 


TimeInterval: Struct(seconds: UIntLong; microSeconds: UIntLong;); 


// Definition of an attribute for configuration 
AttrDefinition: Union (floatValue: Float [8,3]; 
integerValue: UIntLong; 
timeValue: TimeStamp; 


stringValue: String[66];); 
Attribute: Struct (attributeID: UIntShort; Value: AttrDefinition;); 


// Definition of a list of attributes for configuration 


AttributeType: openArray Attribute[50]; 


3.7.7 Programming the Operations 


The Normal and Command Operations contain the application code. They are programmed in 
C++ (C). Routines written in the 3 GL languages, FORTRAN, and PASCAL can be used if they 
are properly declared in ANSI-C. 


As a result of the OTDL compilation, the generic software to handle all input, output, events, 
and so on is generated together with all include files required for the programming of 
operations. Each object type is implemented as a C++ class, generated from the object type 
definition. 
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All identifiers given in the OTDL result in the creation of C++ functions making the operation 
programming look very simple. All references to these identifiers (attributes, connections, 
commands, events) from the operations must be case sensitive since the C++/C languages are 
case sensitive. This gives the impression that you access all identifiers and all functions just by 
referencing them. The programming becomes very straight forward. 


The instructions on how to program the operations that follows walks you through all the 
different ways you access the inputs, outputs and son on but also presents a number of variables 
that you can access to get information about different states and functionalities of your object. 
At the end in Section 3.7.7.7, Summary - Available variables and functions, there are tables 
summarizing all those variables and help functions. 


3.7.7.1 Accessing Attributes and Connections from Operations 


Attribute describes all global variables of the object. The connections describe inputs and 
outputs connected to other objects. From the operations, attributes and connections are accessed 
by their names (case sensitive). In some ways, the attributes and connections together can be 
compared with the input and output parameters of a subroutine programmed in a high-level 
language. 


Powerful functions can be achieved from the operations, i.e., the application code. Attribute and 
connection information can be read and attribute information can be written by referring to them 
as ordinary variables according to the names that they were given in the OTD (see Figure 3-21). 


/part (meanAttribute) 


loLim: Float [8,2] /configure; 
hiLim: Float [8,2] /configure; 
value: Float [8,2]; 
Obj1l: connect AI (ain_abl_dcx) /input; OTDL 
Obj2: connect AI (ain_abl_dcx) /input; 
Obj3: connect AI (ain_abl_dcx) /input; 
optObj: connect ATI (ain_ab1_dcx) /input/optional; 
endPart 


“jalue = 0bj1.VALUE+ (Obj2.VALUE+0b33. VALUE) ; Operanon 


if (optObj == NULL) value = value / 3; program code 
else value = (value + optObj->VALUE) / 4; 


The object type Al has a subscription ain_ab1_dcx that contains among other attributes 
the attribute VALUE. To refer to that attribute just write ConnectionName.VALUE. 


Figure 3-21. Accessing Connections and Public Attributes from Operations 


3BSE 001 012R0501 3-71 


AdvaBuild® Object Type Builder User’s Guide 
Chapter 3 Configuration and Application Building 


3-72 


The example above illustrates that values belonging to connections and public attributes are 


accessible from the operations (application code) in the same way. To the outside world, though, 
only the global attributes are visible. 


The attributes are public - they can be requested through subscriptions, but they cannot be 
connected to other objects (using them as connections). 


Core System 


Conn1|Connvaluet 
Conn2| Connvalue2 
Conn3] Connvalue3 


me 


Connx | Connvaluex Ope nton 
Command 
oe Operations 
eae Attribute 1 
tsid Attribute2 
ores Attributes 
through - 
the core 
system Attributex 
Visible from 
the operations 


“From the operations, attributes and connections are accessed in the 
same way, addressed with their names. To the outside world, only 
attributes are visible.” 


Figure 3-22. Access to Attributes and Connections 


When objects connected through connections need to be effected, the application programmer 


writes a command toward that connection using the connection name and the command syntax 
as described for that object type, see Figure 3-23. 


average.changeLimit (1,4.6); 


Connectionname |= Command name List of parameters 


Figure 3-23. Command Written Towards Output Connection 
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3.7.7.2 Normal Operation 


When the object type description is compiled, a stub is created with all relevant information 
(#define, #include, name of the operation). The Normal Operation code is described with an 
#include statement to an empty source file: 


#define xxxxx 
#define yyyyyy 
#include 2zzzzz 
#include xyz 


void normOperation1 () 


{ 
#include normOpt1 


} 


Figure 3-24. Normal Operation Code 
The part of the Normal Operation code to be written is simply the portions between the begin 
and the end or with C++, the fand the}. 


The Normal Operation basically describes how input connections and attributes are combined to 
generate data to the output attributes and to give commands to connections. The Normal 
Operation is invoked for execution for the following reasons: 


° Object is executing for the first time after system start-up. 
° Time-scheduled execution. 
° Triggered by an input connection. 


° Invoked via the command NormalOperation or from any other command that includes that 
feature. 


See Section 1.8.4.9, Instance Execution to repeat what happens when an instance executes. 
The execution is done in the following phases: 


1. All input connections are read before the Normal Operation execution starts. 


2. The execution of the Normal Operation takes place. The attributes are always available and 
are referred to as if they where variables, see the previous section. Output to connections is 
done by referring to the output connections with the appropriate command syntax. 
Depending on what type of command you specified previously 3 things can happen: 


— Animmediate sending of the command in question will be done (asynchronous) 


— The command is buffered and when the operation is executed, all the buffered 
commands are executed. 
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— The command executes and wait for return parameters and results reported from the 
other object. 


3. At the end of the execution, all modified attributes are updated in the data base. 


You do not have to bother about sending and retrieving data. You use the attributes and 
connections with a very simple syntax. 


There are programming constraints for optional connections which you must follow. 

The connection’s existence is checked before access is attempted. If you try to access an 
optional, but not configured connection, the object is forced into an error state and the Normal 
Operation execution is terminated. 


Exceptions such as run time errors or division by zero, force the object into an error state and the 
Normal Operation execution is terminated. 


3.7.7.3 Command Operation 


When the object type description is compiled, a stub is created for each command with all 
relevant information (#define, #include, name of the operation, syntax for the call). 

The command operation code is described with an #include statement to an empty source file, 
(as was described for Normal Operations). The major addition is that the parameters of the 
command are described as ordinary variables from the operation code. 


An object’s commands consist of user-defined and inherited commands. Only user-defined 
commands can be programmed. The inherited command operations are inherited also regarding 
the implementation. 


The Command Operation execution does not differ from the Normal Operation’s execution. 
Input connections are read before execution and updated attributes are updated in the data base 
after the execution. 


The actions taken on the various commands are free-programmable in the Command 
Operations. Event-detection and handling, exception handling and programming constraints on 
optional connections are the same for Command Operations as they are for Normal Operations 
(described in the previous chapter). 


3.7.7.4 Last Operation 


The Last Operation is executed when an object is deactivated and if the object has ever been 
executed. This operation is supposed to be used in conjunction with the normal operation’s 
coFirstActivation identifier. Example: The application allocates memory in the 
normalOperation’s coFirstActivation, and later on deallocate the memory in the last operation. 


NOTE 


The last operation is a private function, not accessible globally. No input 
connections are read before the last operation is executed. 
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When you read this section, look at the examples provided within this manual. The average 
example in Section 3.4.1, Average Example and the examples in Appendix F, Object Type 
Examples. The examples are included in the delivery of the Object Type Builder. 
Case-Sensitivity 

Since C and C++ are case-sensitive programming languages, all attributes, connections, 
commands, events, etc., must be case-sensitive. If the name of an attribute is Value, write Value, 
not value or VALUE. 

Boolean Variables 


Boolean variables in C and C++ are not given predefined values as they are in most other 
languages. It is recommended that you use the ABB declarations geTrue and gcFalse for true 
and false. 


Accessing Attributes and Single Connections 
The use of an attribute or of a single connection can be compared to applying operations on 
variables of a fundamental type in any 3GL language. For example, the fundamental types in C 
and C++ are char, short, int, long, etc., and in PASCAL, they are integer, real, etc. 
Example 1(in C++) 
value and hilLimare attributes declared in OTDL. Access them as: 

value = 14; 


if (value > hiLim) { 


} 


if (value < loLim) { 


} 

The valid operations on attributes and single connections are restricted as follows: 

° The value of an input attribute and of a single connection can only be read. It cannot be 
assigned values to or from the operation code. 

Example 2 


The attribute inputAtt ribute has the direction input. An assignment as shown below 
results in a compilation error. 


inputAttribute = 14.0; // Compile time error 


Attributes with the direction Bidirect, however, can be assigned a value just as if they where 
ordinary variables of the operation routine. See Example 1 above for the attribute value. 
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Length of String Attributes 
String attributes are a special case. You can check the length of the string attributes by referring 
to currentLength and defaultLength: 
Example 3 
The attribute textAttr is declared with the data type String. 
int remSpace; 


remSpace = textAttr.defaultLength() - 
textAttr.currentLength () ; 


if (remSpace > 20) { 


/* Enough space, add next 20 character line to textAttr */ 


Addressing Bitset Attributes 


Additional information about attributes based on the data types bitset16 and bitset32 follows. 
Each data bit name results in a constant declaration with that name. Using this constant 
declaration, the bits in the bitset data type are addressed as positions in a bitset array (array of 
Booleans) as, for example, the bit error in the attribute STATUS: 


if STATUS[error] 


NOTE 


There is a minor problem when you access single connections based on the data 
types bitset16 or bitset32. As described above, each data bit definition results in a 
constant declaration. Problems arise when the single connection bitset data type 
has constant values with the same name as the object’s own bitset attributes. 


In this case, the object’s constant value overrides the single connection constant 
value. Avoid this problem by using prefixes when the data types (bitset names) are 
declared. 


Accessing Object Connection Attributes 


The use of an object connection attribute can be compared to applying operations on variables 
of a structured type in any 3GL language, i.e., the structured type struct in C, C++ and record in 
PASCAL. 


value = (Obj1.VALUE + Obj2.VALUE + Obj3.VALUE) / 3; 


The valid operations on object connection attributes are restricted—only assignments from the 
connection attributes are valid. You cannot assign to them— only read access is permitted. 
The example below will result in a compilation error. 


Objl.value = 14.0; // Compile time error 
Addressing Bits in Connected Attributes of Data Types Bitset16 and Bitset32 


Attributes based on type declarations, based on the Bitset16 and Bitset32 data types, are 
addressed according to a specific syntax. As mentioned for ordinary attributes, the data bit 
names result in a constant declaration. This constant declaration is used as position in the array 
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of Booleans that constitutes a bitset data type. To ensure that the constant names are unique, 
the bitset constant names of a connection attribute are given the following syntax: 


prefix co + ObjectTypename in correct upper/lower case + “:” 
+ the data bit name 


co<objecttypename>: :<dataBitName> 


Example 4 


You can check STATUS for the input object connections if STATUS is one of the included 
attributes. It is then possible to check if the object is in an error state. In this case the 
Object Type used as input connection has the status bit error in the attribute STATUS. 


if (Obj3.STATUS[coAI::error]== gcTrue) 


Name of Name of co+ObjectType name Name of status bit. It is addressed 
connection STATUS followed by *::”, as a Boolean in an array. The bitName 
attribute gives the position in the array. 


Figure 3-25. Checking Object Status 


Suppress Error Actions 


If a connection is marked with suppress, you can check if the reading of the connection 
succeeded by using the readFailed function. 


Example 5 
if (Obj3.readFailed() == gcTrue) 
Name of A function call which returns true or false. (Data type 
connection is gcBoolean). 


Figure 3-26. Checking the Connection Reading 


The operation may do the following after checking for errors: 
° Continue without using the inputs from that connection. 
° Set the object status to error, 

status[error] = gcTrue; 
° Terminate the operation, 


return; 
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NOTE 


If you continue the operation without checking the result of the input retrieval the 
values from the previous execution will be used. Thus, to get consistent results, 
always check the results of the input retrieval if the Suppress error action is a 
valid parameter for the input connection. 


Optional Connections 


Connections can be optional. They are handled as if they are pointers—refer to pointers in C, 
C++ and PASCAL. You can check this with a short if condition. If the pointer is NULL, no 
connection is made. Optional connections must be accessed as pointers as well. 


Example 6 


Access to the optional object connection opt Obj: 


value = Obj1.VALUE + (Obj2.VALUE + Ob j3.VALUI 


Gl 
~~ 
. 


if (optObj == NULL) value = value / 3; 


else value = (value +optObj->VALUE) / 4; 


Access to an optional single connection optObj1, optObj2, optObj3: 


value = objl + (0bj2 + (0b33)); 


if (optObj1){ value value + (*optObjl1); count++; } 


if (optObj2){ value value + (*optObj2); count++; } 


if (optObj3){ value value + (*optObj3); count++; } 


Referencing External Libraries 


You can refer to external libraries if they are declared as libraries available for the object type. 
Use the ObjectBuilder commands described in Section 3.7.3.2, Library Declaration. 


Checking the Reason for Activation 


When a Normal Operation is activated, you may want to know the reason for the activation. 
(Was it a result of an event or a result of the cyclic activation or of a command?) Check this 
through the variable: 


reasonForActivation(coCyclic|coTriggered|coViaCommand| 
coFirstActivation) 


For all object types that inherit the BasicObject, you can also check whether the activation is the 
first one after a restart or not by checking the status attribute UPDATED. If UPDATED is false, 
the Normal Operation has not executed since the object was created or since the run time 
environment was started. 
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You can check which connection that triggered by checking the attribute triggered on that 
connection. 


Example 7 
switch (reasonForActivation) 
case coFirstActivation: { 
/* perform actions for first execution */ 
} 
case coCyclic: { 
/* perform actions for cyclic execution */ 
} 
case coTriggered: 
/* perform actions for cyclic execution */ 
If pumpStarted.triggered 


If pumpStoipped.triggered 


Checking the Time for the Next Activation 


You can check the time for the previous, and for the next, activation by reading the local 
variables previousExecution and nextExecution. Variables are 21-character strings (space for 
NULL terminator) with the time in Posix format. By moving the nextExecution data into an 
attribute at the end of each NormalOperation execution, the information can be retrieved from 
other objects. They can, for example, subscribe on the attribute. Presenting a list of all objects of 
an object type over the next execution can be done with little effort. 


Checking and changing the cyclic interval 


If the object is configured to execute pure cyclic, it is possible to read the interval time from the 
operation code, The function getCyclicInterval() returns the interval in seconds. 


When an object is configured to execute in cyclic intervals, the interval can be read from the 
new operation getCyclicInterval(). The interval can be modified from the operation code by the 
new operation setCyclicInterval(). 


NOTE 


This is only relevant for cyclic execution, not for scheduled execution. 
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Checking the Parameter for the Current Activation 


You can configure one to seven cyclic conditions, each one with an optional text parameter 
attached (8 1-character string). If such a parameter is configured, you can check the content of it 
by reading the variable parameter. 


Example 8 
switch (reasonForActivation) 
case coCyclic: 


if parameter=="SpecialCasel” 


Accessing Parameters of a Command from the Operation 


Access the parameters of a Command Operation as if they were a parameter to a subroutine. 
Input parameters are read-only and output parameters are write-only. The return of output 
parameters to the caller of the command is taken care of by the run time environment. See the 
command operation implementation examples in Section 3.4.1, Average Example. 


Sending Commands to Output Object Connections 


You can send commands to output object connections with the syntax of the commands that the 
connected object type supports. For example, change the limits of an average object connection 
called anMV from another object type: 


anMV.changeLimits (1, 200.0); 


or if the output connection is optional: 


anMV->changeLimits (1, 200.0); 


Chapter 3, Configuration and Application Building, contains an example with an object type 
that makes a lot of commands to output connections. See that example for a better 
understanding on how to write commands. 


The result of a command sent by an output connection can be checked through the local variable 
resultOfCommand, which is of the datatype OmfStatus. 
The result can be either: 


For all output connections: 
omfFAILURE_ - The target object does not exist or is not resolved. 


Asynchronous: 
omfPENDING- - The command has been sent. 


AsynchronousBuffered: 
omfSUCCESS_ - The command has been buffered. 


Synchronous: 
omfSUCCESS  - The command has been sent and received by the target object. 


The commands can either be executed asynchronously or synchronously. In Figure 3-27 the 
different connection types are illustrated. To select one of the connection types, you use 
predefined functions in the operation code. 
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coAsynchronousOutput() 
coAsynchronousbufferedOutput() 
coSynchronousOutput() 


—  coSynchronousOutput() to objects within the same object handler does not involve 
any access to the underlaying communication systems. It can be seen as an ordinary 
call to a C-function. 


1. Asynchronous output 2. Asynchronous buffered output 


object object 


execution of parameters execution of parameters 


buffer 


time 


3. Synchronous output 4. Synchronous outputs to objects within 
: the same Object Handler. No network 
object access 


execution of parameters 


Object handler 


—viv iyi] gy 


time 


Figure 3-27. Different output connections 


The commands of the available standard object types are described in the Advalnform Object 
Type Reference Manual. Delivery specific object types are described in the same way but the 
documentation may be delivered on separate data sheets. 


Executing the Normal Operation from a Command Operation. 


When you need to execute the Normal Operation from a Command Operation, call the operation 
as a function call 


normalOperation(); 


changeLimits (1, 200.0); 
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NOTE 


From other objects, the command is called NormalOperation. From within the 
own object the operation is named normalOperation. 


Event and Alarm Handling 


As the event and alarm handling is different for Master and MOD 300 systems, the information 
in this section is organized accordingly. The first part describes the Master specific attributes, 
how to send the events/alarms and how to handle Acknowledge and Unacknowledge. The MOD 
300 specific part describes the handling of TCL Billboard messages. 


Master 


Master attributes used for event and alarm handling are pointers to an event treatment 
description in the operator station. The object design determines if these event treatment 
pointers are defined and how they are used. Examples of event treatment pointers in Advant 
Master follow: 


° Err_Tr 
° Lim1_Tr 
° Lim2_Tr 
° Val_Tr 


All event pointers are input attributes with the data type IntShort. They can be assigned a 
default value during object design which can be altered at configuration to give different object 
instances different event behavior. Each event pointer should be given a default according to 
operator station documentation. 


To send messages to the event and alarm system and the local Message Log the following shall 
be done: 


1. Fill in the data section sendEventData with all the information required. 


2. Send the data by calling the function sendEvent. 
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The data section sendEventData contains the following information: 


sendEventData 
eventReason int8 
eventAttribute gcInt16 


eventDescription char (29) 


objectEngUnit char (7) 
processSection ints8 
eventValue TdEventValueType 


errTreatReference gcInt1l6 


timeQuality ints 
useSystemTime gcBoolean 
eventTime TdBsTimeStamp 
blockConditions TdBlockCondType! 


All values are defaulted to 0, gcFalse and similar defaults. 


Explanation: 


eventReason as an integer value according to Appendix H, Event Handling Constants, 
where valid event reasons are described. The event reasons are declared as constants and 
can be referenced directly in the operation code. eventReason is a variable that can be 
referenced directly: 


sendEventData.eventReason = DCX_ALARM_ON; 


eventAttribute as an integer value according to Appendix H, Event Handling Constants, 
where valid event properties are described. The event properties are declared as constants 
and can be referenced directly in the operation code. 


eventDescription is by default filled in with the objects description. If you want to send 
other information to the event and alarm system using the description field you can do that. 


objectEngUnit and processSection can be filled in already at the first initialization of the 
object if the information exists for the object type. The information is simply moved from 
the attributes of the object into the variables. 


An important feature is the ability to specify whether the time stamp on the event is to be 
taken from the system clock or to be provided by the operation. If to be read from the 
system clock (which you do not need to take care of) at the time the event is raised, set the 
parameter sendEventData.useSystemTime to gcTrue; if not, set it to gcFalse. If false, the 
time is set through the parameters sendEventData.eventTime.seconds and 
sendEventData.eventTime.microSec 


seconds is the number of seconds since 00:00:00, January 1, 1970 (UIntLong). 
-microSec is the fractional time in microseconds~ (UIntLong). 


timeQuality, and eventTime are set by the run time environment if 
useSystemTime is true. 


1. 


Consists of 3 booleans in a bitset definition. See the description of blockConditions on next page. 


2. Please study the C function. ftime. Use ftime to retrieve a system time. 
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° eventValue and errTreatReference are assigned if that information exists for the object 
type. Since some object types may have different error treatment for different errors, this 
may have to be assigned for each event. Otherwise, fill it in during initialization. 


eventValue is filled according to: 


sendEventData.eventValue.unionTag = DCX_REALV; // Float 
sendEventData.eventValue.u.valueFloat = VALUE; 


sendEventData.eventValue.unionTag = DCX_INTV; // Integer Long 
sendEventData.eventValue.u.valueInteger = 100; 


sendEventData.eventValue.unionTag = DCX_BOOLV; // Boolean 
sendEventData.eventValue.u.valueBoolean = gcFalse; 


errTreatReference: 


sendEventData.errTreatReference = LimTr; 


° blockConditions are assigned if they exist in the object type. Otherwise, they are set to 
false. You can also do this in the initialization phase. 


sendEventData.blockConditions[TdAlarmBlock]= gcFalse; 
sendEventData.blockConditions[TdPrintBlock] = gcFalse; 
sendEventData. blockConditions[TdRepFailBlock] = gcFalse; 


Example 9 

switch (reasonForActivation) 

case coFirstActivation: 
sendEventData.useSystemTime = gcTrue; 
sendEventData.objectEng Unit= unit; 
sendEventData.processSection = SUB_SYSTEM; 
sendEventData.valueType = DCX_REALV!; 
or if an Integer value shall be passed: 
sendEventData.valueType = DCX_INTV; 


° valueFloat, valueInt or valueBoolean and errTreatReference are assigned if that 
information exists for the object type. Since some object types may have different error 
treatment for different errors, this may have to be assigned for each event. Otherwise, fill it 
in during initialization. 


sendEventData.valueFloat = value; 


sendEventData.errTreatReference = LimTr; 


1. Allowed formats are DCX_REALV (valueFloat), DCX_INTV (valueInteger) and DCX_DIGV (valueBoolean). 
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° blockConditions are assigned if they exist in the object type. Otherwise, they are set to 
false. You can also do this in the initialization phase. 


sendEventData.blockConditions[TdAlarmBlock]= gcFalse; 
sendEventData.blockConditions[TdPrintBlock] = gcFalse; 
sendEventData.blockConditions[TdRepFailBlock] = gcFalse; 


timeQuality, eventMillitime and eventTime are set by the run time environment if 
useSystemTime is true. 


UNACKNOWLEDGE and ACKNOWLEDGE (Master specific) 


Object types that have the ability to generate alarms must also implement a command to receive 
an unacknowledged message from the alarm list and one command for acknowledge support. 
The first command sets the acknowledge status bit, if any. The ACKNOWLEDGE command 
sends a message to all alarm lists that the object is acknowledged. You implement the 
UNACKNOWLEDGE and ACKNOWLEDGE commands as follows: 


UNACKNOWLEDGE 


The UNACKNOWLEDGE operation is a subset of the command ORDER, see the 
Advalnform Object Types Reference Manual. Treat the input parameters of the ORDER 
command according to: 


° opCode must have the value dcSET_UNACK_DCX. 
° Disregard opProp, typeOfReq, eventLog, ID, aValue and dValue. 
° If OK, return dcGRANT in the status parameter; if not, return dCNOT_ALLOWED. 


ACKNOWLEDGE 


The acknowledge operation is described with the command ACKNOWLEDGE, see the 
Advalnform Object Type Reference Manual. Treat the input parameters according to: 


° opCode must have the value d ACKNOWLEDGE_DCX. 


° Disregard opProp, typeOfReq, eventLog and ID for applications which are not provided 
in the IMS product. 


° If OK, return dcGRANT in the status parameter; if not, return ddNOT_ALLOWED. 


When the acknowledge operation has completed its internal functions, for example, changing 
the value of one or several status bits, it must acknowledge the alarm in all other alarm lists 
with the function call: 


acknowledgeLists (eventProperty); 


where event property is set to | for applications that are not provided in the IMS product. 
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TCL Billboard messages (MOD 300) 


The Object Type Builder in MOD 300 can use TCL Billboard messages. The TCL Billboard 
messages are sent to the OS TCL Billboard and are not stored locally. There are specific 
attributes to keep track of a UNIT name which must be available. The message is sent through 
the EADISTR (Event and Alarm Distributor) object which is described in the Advalnform 
Object Type Reference Manual. 


To send a TCL Billboad message: 


1. Fill in the data section sendEventData with all the information required. 
2. Send the data by calling the function sendEvent. 


The data section sendEventData contains the following information: 


sendEventData 


eventValue TdEventValueType 
useSystemTime gcBoolean 
eventTime BsTimeStamp 


priority UIntSmall 
All values are defaulted to 0, gcFalse and similar defaults. 
Explanation: 


° eventReason is EAD_ER_ TEXT MESSAGE. 


° eventA ttribute is an integer value describing the message type. There is only one possible 
value: MOD_EA_MSG_NORMAL; 


° An important feature is the ability to specify whether the time stamp on the event is to be 
taken from the system clock or to be provided by the operation. If to be read from the 
system clock (which you do not need to take care of) at the time the event is raised, set the 
parameter sendEventData.useSystemTime to gcTrue; if not, set it to gcFalse. If false, the 
time is set through the parameters sendEventData.eventTime.seconds and 
sendEventData.eventTime.microSec 


—  .seconds is the number of seconds since 00:00:00, January 1, 1970 (UIntLong). 
—  .microSec is the fractional time in microseconds! (UIntLong). 


eventValue is assigned with the text value and the corresponding alarm limit or old value. For 
compare value shall contain the TCL UNIT name, 12 characters: 


sendEventData.eventValue.unionTag = EAD_VAL_STRING; // Text 
strcepy ( (char *) sendEventData.eventValue.u.valuetext, Text_, 
(char *) textString); 
sendEventData.compareValue.unionTag = EAD_VAL_STRING; // Text 
strcpy ( (char *) sendEventData.compareValue.u.valuetext, Text_, 
(char *) textStringWithUnitName) ; 


Priority is set to one of 3 priority levels: 
EAD_LOW_PRIO_ALARM = 0 
EAD_MED_PRIO_ALARM = 1 
EAD_HIGH_PRIO_ALARM = 2 


1. Please study the C function. ftime. Use ftime to retrieve a system time. 
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Raising Events 


To raise an event, (which is a message to any other object subscribing to it and has nothing to do 
with event and alarm messages) reference the event name, as declared in the OTDL, as a 
function. For example: 


eventHiLim (); 


This will raise an event to anyone that subscribes upon it. 


Error Handling, Returning the Result of the Operation 


The result of an operation is returned as return parameters to the sender of the command. As the 
User Objects currently do not wait for a command to be executed but continues as soon as the 
command is sent, the return data will not reach the sender if the sender is a User Object. If the 
command is issued from for example the User API, return parameters will be handled though. It 
is strongly recommended to provide two return parameters for each command. One that 
provides a status Ok or false. Return dcGRANT for success or ddNOT_ALLOWED for failure. 
The second provides a text index back. See the textIndex declarations in the decodes library. 
You can also find the decodes include file under: 


/opt/advant/UserAPI/include/ 


It is also possible to report the success or failure of an execution of an operation through the 
core system. The result is reported into two return variables. They are returned to the core 
system by the object handler after executing the objects operation. View these two variables as if 
they were return parameters to each operation. The parameters are: 


° returnOmfCode (integer byte) 


Example 10 


Examples of how to return from an operation: 
returnOmfCode = omfCAP_SUCCESS; 


return; // OK, return with success return parameters 


returnOmfCode = omfCAP_PARAMETER; 
return; // Illegal parameters, return with 


// error return parameters 


Controlling the persistent storage from operation code. 


The Object Attributes can be configured to be stored persistent after an operation has been 
executed. This is configured by the ObjectUtil tool (See Appendix D). 


The operation code can change whether an object shall store data persistent during run-time by 
calling the functions: 


void enableAutoPersistentStore() ; 


void disableAutoPersistentStore() ; 
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The operation code can force an immediate persistent storage and commit of the attributes by 
calling the function: 


void storeObjectPersistent (); 


Controlling whether an object shall be deactivated after an execution 


In the operation code is possible to deactivate the current object after the operation is executed. 
This could be useful when the object has entered an unrecoverable error state. This is made by 
calling the function: 


void coDeactivateObject () ; 


Exit from the Operation 


You can terminate the operation with an ordinary return statement. Remember to fill in the 
correct return parameters before terminating as described in the previous section. 


3.7.7.6 C declarations of attributes and parameters 


Table 3-4 gives the C declarations corresponding to the OTDL data type declarations. 
In general, there is a C data type defined for each OTDL data type and with the same name: 


Table 3-4. C format for OTDL declarations 


OTDL Data type C Data type 

Float Float 

Double Double 

IntSmall IntSmall 

IntShort IntShort 

IntLong IntLong 

UIntSmall UIntSmall 

UIntShort UIntShort 

UlntLong UIntLong 

Boolean gcBoolean 

String gcString 

Bitset16/Bitset32 | Bitset16 and Bitset32 have no corresponding C representation. You 
address each bit by itself as a boolean, in an array of booleans. 
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3.7.7.7 Summary - Available variables and functions 


Table 3-5. Variables used in operation programming 


Variable name 


reasonForActivation 


Data type 


enum 


Short explanation 
Describes the reason for the normalOperation to 
be executed: 
coCyclic: Scheduled 
coTriggered: Triggered 
coViaCommand: Command activation 
coFirstActivation: First execution 


resultOfCommand 


omfStatus 


Returns the result of the last issued command 
omfPending for success, omfFailure for failure. 


previousExecution, 
nextExecution 


string(21) 


Presents the time for the current execution 
(previousExecution) and for the next execution in 
string format 


sendEventData 


struct 


A set of data to be filled in before sending a 
message to the event and alarm system with the 
sendEvent function. 


returnOmfCode 


int8 
int8 


Return parameters from the operation. Will be 
returned through the core system to the receiver 
if the receiver wants them. 


Table 3-6. Functions used in operation programming 


defaultLength 


Function name Date WPS Short explanation 
returned 

sendEvent - Sends the message as described in 
sendEventData to the event and alarm system. 

readFailed gcBoolean Returns true if the reading of a connection fails 
and false if it succeeded. 

triggered gcBoolean Returns true if the connection was triggering the 
execution of the normalOperation. 

currentLength and gclnti6 Returns the current and the default length 


respectively of an attribute or parameter 


coAsynchronousOutput() 


The command is executed asynchronously. 


coAsynchronousBuffered 
Output() 


All the commands are buffered and executed 
asynchronously. 
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Table 3-6. Functions used in operation programming (Continued) 


Function name Balas) pe Short explanation 
returned 
coSynchronousOutput() - The commands are executed synchronously, i.e. 
the status of the commands are returned before 
the next command is executed. 
getCyclicinterval If the object is configured to execute pure cyclic, 
it is possible to read the interval time from the 
operation code, The function getCycliclnterval() 
returns the interval in seconds. 
setCycliclnterval The interval can be modified from the operation 
code by the new operation setCycliclnterval(). 
enableAutoPersistent - The function enables automatic storing of 
Store() updated attributes into the database 
disableAutoPersistent - The function disables automatic storing of 
Store() updated attributes into the database 
storeObjectPersistent() - Forces an immediate storage of the updated 
attributes and performs a commit. 
coDeactivateObject() Deactivates the object itself e.g when an 
irrecoverable state has been reached. 


3.7.7.8 C++ compiler directives 


To add C++ compiler directives to User Object compilations you modify the environment 
variable COCCC which is normally set to CC. 


1. Start the Object Type Builder terminal window by selecting AdvaBuild Object Type 
Builder from the IMS menu. 


2. Set the COCCC environment variable. Example: 


export COCCC="CC -DTestPrintouts”’ 


3.7.8 FAQ (Frequently Asked Questions) 


What steps are needed to do in Object Type Builder to rebuild an object handler if I change the 
Object Type Definition? 


You need to re-do almost all steps. Build up a script that runs Object Type Builder to 
remove all traces of the object handler and the object type(s) and then to include it all 
again. There are examples on such scripts under 
/opt/advant/ObjectBuilder/examples. 
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Chapter 4 Operation 


4.1 Operating Overview 


Object Type Builder has no run time operating features of its own. Documentation of your User 
Object types, however, is discussed in this section. 


You can document a User Object type by Printing out your OTDL text file. 


User Object operations, and their private functions, consist of ordinary software which can be 
most easily documented using a printer. 


During the design and analysis phase, see Section 3.1, Design Considerations, and Section 3.5, 
Application Procedures, and make a graphical drawing of your application. There are several 
Case tools available for such tasks. 


4.2 Product Operation 


This section is not applicable. 


4.3 Runtime Tutorial 


This section is not applicable. 


4.4 Operating Instructions 


This section is not applicable. 


4.5 Runtime Operation Menus 


This section is not applicable. 


3BSE 001 012R0501 4-1 


AdvaBuild® Object Type Builder User’s Guide 
Chapter 4 Operation 


4-2 3BSE 001 012R0501 


AdvaBuild® Object Type Builder User’s Guide 
Section 5.1 Preventive Maintenance 


Chapter 5 Maintenance 


5.1 Preventive Maintenance 


This section is not applicable. 


5.2 Hardware Indicators 


This section is not applicable. 


5.3 Error Messages 


5.3.1 OTDL Compilations 


Error messages during OTDL compilation: 
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Error message: Invalid identifier, already defined 
— Explanation: The specified identifier is already defined and is not unique. 


— Action: Remove the old name from the tables or use another identifier name. 
A typical situation is when you compile an OTDL and the object type is already 
compiled into the system. If done with ObjectParser you can remove the type with 
ObjectUtil but if done with ObjectBuilder, you must use ObjectBuilder to remove it. 


Error message: Invalid identifier, not defined 

— Explanation: The specified identifier cannot be used because it is not defined. 
— Action: Define the missing identifier or use an already existing identifier. 
Error message: Invalid identifier, not possible to select 

— Explanation: The specified identifier cannot be selected for an object connect. 
— Action: Validate the defined object connection. 

Error message: Invalid identifier, reserved identifier 


— Explanation: The specified identifier name is not valid and it is reserved by the 
system. 


— Action: Use another name as the identifier. 
Error message: Invalid default value assigned, mismatch to the constraint values 
— Explanation: The defined default value does not suit the defined constraints. 


— Action: Change the default value or the constraint value to suit the defined 
constraints. 


Error message: Invalid base data type for an already defined data type 
— Explanation: The local defined data type is an invalid base data type. 
— Action: Validate the specified local data type definition. 
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Error message: Invalid data type definition, openArray 
— Explanation: The data type open array has been used incorrectly. 


— Action: Refer to the syntax description, in particular to the paragraph which describes 
the open array and struct data types. 


Error message: Invalid direction defined for a data type of openArray 

— Explanation: The specified data type has to be of the /input or /bidirect direction. 
— Action: Change the direction or the data type. 

Error message: Invalid data bit position, already defined 


— Explanation: The specified bit position is already defined for the bitset and the 
position has to be unique. 


— Action: Remove the old bit definition or use a free bit position. 
Error message: Invalid bitset type, data type mismatch 
— Explanation: The inherited bitset data type does not suit the local extension of it. 


— Action: Modify the local extension to suit the inherited bitset data type (Bitset16 or 
Bitset32). 


Error message: Invalid value for the data type 

— Explanation: The defined value is out of range for the data type. 

— Action: Change to another data type or use a value which suits the data type. 
Error message: Invalid max value 

— Explanation: The value is larger than the defined max limit for a parameter/data type. 
— Action: Define a value which suits the parameter/data type. 

Error message: Invalid value defined 

— Explanation: Mismatch between the value type and the data type. 

— Action: Modify either the data type or the value. 

Error message: Invalid field length 

— Explanation: The field length is greater than the defined max limit. 


— Action: Define a shorter field or if possible increase the string declaration for the data 
type. 
Error message: The subscription has not the status attribute defined 


— Explanation: The defined subscription name does not include the mandatory status 
attribute which must be included for an object connection. 


— Action: Use a subscript which includes the status attribute or use a single connection 
instead. 


Error message: Invalid subscription attribute name, not defined 


— Explanation: The attribute names used by a subscription must all be defined by the 
object type. 


— Action: Remove the invalid attribute name or define a new attribute with that missing 
name. 
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° Error message: Invalid number of command parameters for an already defined 
command name 


— Explanation: The number of parameters must be the same as for the command that is 
already defined. 


— Action: Define it as a new command name or change the number of command 
parameters to suit the command already defined. 


° Error message: Invalid command parameter name for an already defined command 
name 


— Explanation: The parameter names must match the names which are defined for the 
command. 


— Action: Define it as a new command name or change the parameter name to match 
the command already defined. 


° Error message: Not valid to define, when running source gen mode 
— Explanation: Invalid parameter to define when running the source generation mode. 


— Action: Remove or change the parameter or use the ObjectParser utility to get the 
OTDL file compiled. 


° Error message: Invalid log file name 
— Explanation: Error has occurred to get the log file opened. 
— Action: Investigate why open file operation does not work. 
° Error message: Invalid option to run the precompiler 
— Explanation: Invalid argument mode when running the precompiler/PARSER. 
— Action: Validate the argument list for the executed command. 


° Error message: The mode sourcegen (default) requires to have the qualifier \’inh=\’ 
defined to \’yes\’ 


— Explanation: Invalid inherited argument when running the precompiler/PARSER. 


— Action: Validate the inherited argument for the executed command. If defined, it 
must be set to yes. Otherwise, change to a mode other than source generation. 


° Error message: Invalid object type file name 


— Explanation: Invalid object type file name has been defined for the executed 
command. 


— Action: Validate the object type file name to an existing name. 

° Error message: Close operation failure for object type file 
— Explanation: Error has occurred to get the object type file name closed. 
— Action: Investigate why close file operation does not work. 


Compilation errors may occur when the source code files generated from the OTDL are 
compiled. 
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5.3.2 Errors from Operation Compilations 


The C++ compiler is used to compile operations. All error messages come from the C++ 
compiler. Please read the appropriate C++ compiler documents to understand and correct those 
errors. 


An operation that is deleted is automatically replaced with an empty operation which is 
compiled as part of the deletion. This avoids unresolved references during linking. Compiling 
an empty operation produces compilation warnings because no variables are referenced. Ignore 
these warnings. 


Errors detectable in compile time are: 
° Only attributes and connections defined at object type design can be accessed. 


° The same type checks are performed on attributes and connections as are performed on 
other types definable in the language. 


° Connections and input attributes are impossible to assign values to. 
° The syntax of commands is checked. 


° Commands are allowed only toward output object connections. 


5.3.3 ObjectBuilder Error Messages 
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ObjectBuilder responds with an error action when a request fails. This may be due to an invalid 
or illegal command. It may also indicate other types of problems. 


° Error message: Object type <name> not compiled 
— Explanation: The specified object type is not compiled, so it cannot be used. 
— Action: Compile the missing object type or use an already compiled object type. 
° Error message: Object type not selected 
— Explanation: Object type is not selected, the requested service cannot be used. 
— Action: Select appropriate object type. 
° Error message: Object type <name> not added 
— Explanation: The specified object type is not added, so it cannot be used. 
— Action: Add the missing object type definition file. 
° Error message: Object type <name> not assigned 


— Explanation: No object type is assigned to the object handler, so it is not possible to 
build the object handler. 


— Action: Assign the appropriate object types. 
° Error message: Object type <name> already assigned 


— Explanation: The object type is already assigned to an object handler in the same 
node. 


— Action: Deassign the object type from the object handler it is assigned to and assign 
the object type to the appropriate object handler. 
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Error message: Object type <name> already exist 
— Explanation: The specified object type is already compiled. 


— Action: Use the compile object type or delete the compiled object type and add and 
compile a new object type. 


Error message: Could not delete, object type <name> is inherited 

— Explanation: The specified object type is inherited by another object type. 
— Action: Delete the inheriting object type and then delete the selected object type. 
Error message: Failed to delete object type <name> 

— Explanation: The specified object type is not owned by you. 

-— Action: Use ObjectUtil to delete the selected object type. 

Error message: Denied to delete object type <name> 

— Explanation: The specified object type is not owned by you. 

— Action: Ask the owner of the object type to delete the selected object type. 
Error message: Could not delete, instances exist of object type <name> 

— Explanation: The specified object type has instances. 

— Action: Remove the instances and then delete the object type. 

Error message: Could not delete, object type <name> is connected 

— Explanation: The specified object type is connected to another type. 

— Action: Remove the connection and then delete the object type. 

Error message: Could not instantiate, object type <name> is abstract 

— Explanation: The specified object type cannot instantiate. 

— Action: Inherit the object type and then instantiate inheriting object type. 
Error message: Library <name> already exist 

— Explanation: The specified library is already defined. 

— Action: Use another name for the library. 

Error message: Library <name> already assigned 

— Explanation: The library is already assigned to an object type. 

— Action: Delete the library if you want to replace it. 

Error message: Library <name> is not declared 

— Explanation: The specified library is not declared, so it cannot be used. 

— Action: Declare the missing library or use an already declared library. 
Error message: Operation <name> does not exist 

— Explanation: The specified operation is not declared, so it cannot be used. 


— Action: Add the missing operation or use an already declared operation. 
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Error message: Operation <name> already exist 

— Explanation: The specified operation is already declared. 

— Action: Delete it if you really want to replace it. 

Error message: Description too long 

— Explanation: The description is too long. 

— Action: Repeat the command with a shorter description. 

Error message: Can not find file <name> 

— Explanation: The file des not exist. 

— Action: Repeat the command with right path and file name. 

Error message: Failed to create file <name> 

— Explanation: The file could not be created. 

— Action: Repeat the command with an existing path and a nonexisting file name. 
Error message: File <name> already exist 

— Explanation: The file could not be created because it already exists. 
— Action: Repeat the command with a nonexisting file name. 

Error message: Failed to compile object type <name> 

— Explanation: The ObjectBuilder environment is not correct. 


— Action: An error file is produced under /ipa/co/types/<name>/cootdlcompile.err. 
Read this file and try to solve the problem. If the problem cannot be solved 
immediately, forward the file to ABB together with an error description and the 
OTDL file that caused the error. 


Error message: CC:.warning 
— Explanation: No failure, these are just normal compilation warnings. 


— Action: Read the warnings and modify the OTDL or operation file according to the 
warnings. Add the modified file to the tool and compile it. 


Error message: Failed to add library 

— Explanation: The ObjectBuilder environment is not correct. 

— Action: If the problem cannot be solved, forward an error description to ABB. 
Error message: Can not find library <name> 

— Explanation: The library does not exist. 

— Action: Repeat the commands with right path and library name. 

Error message: Failed to get interface file 

— Explanation: The ObjectBuilder environment is not correct. 


— Action: If the problem cannot be solved, forward an error description to ABB. 
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Error message: Failed to modify interface file <name> 

— Explanation: The ObjectBuilder environment is not correct. 

— Action: If the problem cannot be solved, forward an error description to ABB. 
Error message: Failed to modify description 

— Explanation: The ObjectBuilder environment is not correct. 

— Action: If the problem cannot be solved, forward an error description to ABB. 
Error message: Failed to modify library 

— Explanation: The ObjectBuilder environment is not correct. 

— Action: If the problem cannot be solved, forward an error description to ABB. 
Error message: Failed to delete library 

— Explanation: The ObjectBuilder environment is not correct. 

— Action: If the problem cannot be solved, forward an error description to ABB. 
Error message: Error in library Path 

— Explanation: The library could not be found. 

— Action: Modify the path. 

Error message: Object handler <name> already exist 

— Explanation: The specified object handler is already added. 


— Action: Use the built object handler or delete the built object handler and add a new 
object handler. 


Error message: Object handler <name> is active 

— Explanation: The specified object handler is already running. 

— Action: Stop the object handler and repeat the command. 

Error message: Object handler <name> does not exist 

— Explanation: The specified object handler is not defined. 

— Action: Add the specified object handler and repeat the command. 

Error message: Object handler not selected 

— Explanation: Object handler is not selected, the requested service cannot be used. 
— Action: Select appropriate object handler. 

Error message: Object type not assigned to object handler 

— Explanation: The specified object has no assigned object type. 

— Action: Assign an object type and then repeat the command. 

Error message: Unrecognized qualifier combination 

— Explanation: The combination of qualifiers to the command are not supported. 


— Action: Repeat the command with appropriate qualifiers. 
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° Error message: <name> is a directory 
— Explanation: The given parameter is a directory. 
— Action: Repeat the command with appropriate parameter value. 
° Error message: No access to current working directory 
— Explanation: Error has occurred affecting access to the current working directory. 
— Action: Investigate why access to directory is not possible. 
° Error message: Path of current working directory to long 
— Explanation: The length of the given parameter value is too long. 
— Action: Repeat the command with a shorter description. 
° Error message: List file already exist 
— Explanation: The specified list file already exists. 
— Action: Use another name for the list file or delete the old file. 
° Error message: Internal error: Message not found 
— Explanation: Internal error. 


— Action: Forward an error description to ABB. 


5.4 Fault Finding and User Repair 


The first thing to do if something fails is to check for an error message - normally, there will be 
one. If the error message is self-explanatory, correct according to the message. If not self- 
explanatory, search for the error message in the lists of error messages above. Read the 
explanation and the suggested action. Perform the action and try again. 


If the action suggested is to contact your ABB representative, make sure that you have all the 
information needed to file a Problem Report. Read the AdvaInform Basic Functions release 
notes and send your Problem Report to your ABB representative. 
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a-z: Hyphen (-) defines a range; that is, any lowercase letter. 


[a-z]: Indicates a character class containing all the lowercase letters. 


[‘a-z]: A negated character class; that is, any character except a lowercase letter. 


italic: An italic type string is a definition expression. 


{italic}: A repetition of the enclosed definition expression, zero or unlimited times. 


{italic}": A repetition of the enclosed definition expression, zero or max n times. 


italic yp: An optional definition expression. 


italic] | italic2: Either expression italic! or italic2. 


literal: Literals are part of the syntax. 


literal: Boldface literals are reserved keywords. Keywords are case-insensitive. 


/literal: An optional reserved keyword. 


A.1.2 General Expression Definitions 
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blockComment: ==/* {blockText} */ 
blockText:== [/V*| 


boolNum:== [true | false | set | reset] 


descriptionText:= =" {text }>°” 
digit:== [0-9] 
eol:== CrLf 


floatNum:== ~opt{ digit} . {digit} 
hex:== [0-9| A-F] 

hexNum:==[%h {hex} 

octal:== [0-7] 

octNum:==% 0 {octal} 

identifier:== [letter] {letter | digit}!” 
letter:== [a-z| A-Z| _ ] 
lineComment: == //{lineText} eol 
lineText:== [eol] 

nintNum: == -{ digit} 

pintNum:== {digit} 

stringText:==" {text}*°” 


text:== [*”] 
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In stringText, a string is defined as a set of characters between straight quotation marks (’’), 
provided that the string does not include straight quotation marks (’’). The lineComment is 
enclosed between // and eol and blockComment is enclosed between /* and */. 


Keywords (bold literals) are all case-insensitive in the OTD language. They are reserved words 
and cannot be defined as identifiers. Known keywords are listed in Section A.5, Reserved 
Keywords. 


A.2 Object Type Definition Syntax 


An object type definition is described in the Object Type Definition Language (OTDL) and is 
compiled by a parser. 


An object type definition is defined by its subdefinitions, which are listed below: 
° Object type header 

° DataTypes 

° Part (basic) 

° Base Attributes 

° Part (user-defined parts) 

° Attributes 

° Connections 

° Subscriptions 

° Commands 


° Events. 


Comments are allowed in addition to these subdefinitions. Refer to Section A.2.8, Comments. 


A.2.1 Object Type Header 
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objectTypeDefinition:== objectTypeName description gy; toolNames op; inherit yy, abstract yyy 
dataTypeDefinition, 
{partDefinition} 
subscriptionDefinition op 
commandDefinition oy, 
eventDefinition gn 
end 
Enclose an object type definition with an object type name and the reserved word end. 
objectTypeName:== identifier 
The objectTypeName is a type identifier. The objectlypeName must be unique for the system 
configuration. It is validated as unique at compilation. 
description:== /descr(descriptiontext) 


toolNames:== /tool(toolName {, toolName }) 


The description is of the descriptionText type and is optional. This field should contain a short 
subdefinition description. 
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NOTE 


The description must be enclosed in quotation marks (’’). The description cannot 
contain quotation marks. 


toolName:== identifier 

The toolName must be unique within the toolName list. 
inherit:== /inherit (ObjectTypeName) 

The inherited objectTypeName must be an already defined object type name. 
abstract:== /abstract 


The object type is abstract. It cannot be configured into object instances. Data types, parts, 
attributes, connections, subscriptions, commands and events are inherited and added to the new 
object type definition, as if they were explicitly defined. If inherit is omitted, it defaults to a 
predefined base object type (BasicObject). Refer to Section A.2.3, Basic Part. 


dataTypeDefinition:== (Refer to Section A.2.2, DataTypes.) 

partDefinition:== (Refer to Section A.2.3, Basic Part, and Section A.2.4, Parts.) 
subscriptionDefinition:== (Refer to Section A.2.5, Subscriptions.) 
CommandDefinition:== (Refer to Section A.2.6, Commands.) 


eventDefinition:== (Refer to Section A.2.7, Events.) 


Syntax 

dataTypeDefinition:== /typedef 
{ typeDefinitions } 

endTypedef 


typeDefinitions is an optional field. You can define an optional number of local defined data 
types with this field. 


typeDefinitions:== dataTypeName: dataTypeDef; 
dataTypeName:== localType 


The dataTypeName is validated to ensure that it is a unique data type for this object type 
definition. 


The bitset data types can be inherited and extended with the definitions of the unused bits. For 
example, the inherited data type Status can be locally extended with the definitions of the bits 4- 
32. Refer to Section A.2.3, Basic Part, Basic Part, for more information. 


dataTypeDef:== dataType| bitsetType| struct | union | enum | shortEnum | bitset | array | 
openArray 


dataType:== double | float | string | dataTypeName| IntLong | UIntLong | IntShort | 
UIntShort | IntSmall | UIntSmall | Char | Boolean 


double:== Double precisionDef,,, 


precisionDef:== [length precision g,;| 
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precisionDef cannot be omitted—you must define it. If both are defined, Length must be 
greater than precision. The precisionDef field is validated to suit the defined dataType (Float or 
Double). 


length:== pinetum 
precision:==, pinetum 
If precision is omitted, it is defaulted to 0. 
float:== Float precisionDef,,; 
string:== String[length] 
String length! is limited to 1,024 bytes. 
dataTypeName:== localType | globalType 
localType:== identifier 
The local data type name is a local data type defined for the object type definition. 
globalType:== identifier 
The global data type name is a global data type defined for all object type definitions. 
struct:== Struct ({ structUnionDefinitions }) 
structUnionDefinitions:== structUnionMemberName: dataType; 


In a struct, only the last structUnionMember may be of a dataType, which is or includes (if the 
data type is struct) an openArray. 


structUnionMemberName:== identifier 
union:== Union ({ structUnionDefinitions }) 
bitset:== bitsetType dataBitParameters yy, 
bitsetType:== Bitset32| Bitset16 
dataBitParameters:== (dataBitName: Bit(position); {dataBitName: Bit(position);}) 
dataBitName:== identifier 

The dataBitName is validated as a unique name within the bitset definition. 
position:== pintNum 

The position must be unique within the bitset, i.e, only one position can be referred to, by one 


dataBitName. pintNum is limited to 16 or 32, dependent on the bitsetType. The first bit is 
numbered 1. 


Already defined bits cannot be altered, i.e., the inherited data type TdStatus cannot redefine the 
bits 1-3. Refer to Section A.2.3, Basic Part, Basic Part, for more information. 


openArray:== openArray dataType[length] 
Array:== Array dataType[length| 


The dataType cannot be, or include, an openArray. For example, openArray of openArray 
cannot be defined.The length is 1 to 65 535 (unsigned integer short). 


enum:== Enum ({ enumDefinitions}) 


1. Please note that string length is given in C- syntax, i.e., with an extra byte for the null terminator in C. 
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The enum values are of datatype IntLong. 
enumDefinitions:== enumMemberName: enumValue; 
enumMemberName:== identifier 

The enumMemberName must be unique within the data type definition. 
enum Value:== pintNum | nintNum 

The enum value must be unique within the definition. 


shortEnum:== ShortEnum ({ enumDefinitions}) 


The shortEnum values are of datatype IntShort. 


The object type definition must contain a part (basic). This part is inherited either from a user- 
defined object type (refer to Section A.2.4, Parts) or (if not, /Ainherit is given) from a standard 
base object type BasicObject). 


The BasicObject type definition follows: 
BasicObject /descr(’’Standard Base object type’’) /abstract 
/typeDef 
/* Base Data type syntax, refer to Section A.2.2, DataTypes.*/ 
TdStatus: Bitset32 ( 
active: Bit(1); 
error: Bit(2); 
updated: Bit(3);); 
endTypedef 


/part (basic) /descr(’’Part Basic standard definition’) 

/* Base Attribute syntax, refer to Section A.2.4.1, Attributes.*/ 
NAME: TdName /input /configure; 
DESCRIPTION: TdDescription /input /configure; 
STATUS: TdStatus; 

endPart 

/command 
Delete: (); 

Deactivate: (); 

Copy: (TdName /input objectName); 

NormalOperation: (); 
endCommand 


end 
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A.2.4 Parts 
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TdName and TdDescription are global data types of the primitive data types String[21] and 
String[29]. 


There is one more predefined base object (DDCSObject), which is used for some ABB DCS 
objects, that lacks Status and Description. This object type has a basic part without the 
Description and Status attributes defined. To get this, /nherit is given with the object type name 
DCSObject. 


The DCSObject definition follows: 
DCSObject /descr(’ ABB Base object type”) /abstract 
/part (basic) /descr(’ ABB part basic definition’) 
NAME: TdName /input /configure; 
endPart 
/command 
Delete: (); 
Deactivate: (); 
Copy: (TdName /input objectName); 
NormalOperation: (); 
endCommand 


end 


partDefinition:== [part (partName) Description gy, 
{ attributeConnectionDefinition; } 
endPart 
Enclosed by the part definitions, all optional attributes and connections are defined. 


An optional field, partDefinition can be used zero or unlimited times. A user-defined part may 
contain a mixture of attributes and connections, defined in any order. 


partName:== identifier 


The user-defined partName is validated as a unique name for this object type definition, 
including the inherited part names. 


attribute ConnectionDefinition:== attributeDefinition | connectionDefinition 
attribute Definition:== (Refer to Section A.2.4.1, Attributes.) 


connectionDefinition:== (Refer to Section A.2.4.2, Connections.) 
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A.2.4.1 Attributes 
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Syntax 
attribute Definition:==attributeName: attributeType 
attributeName:==identifier 


The attributeName is validated as a unique name for this object type definition, including the 
inherited names. 

attributeType:== ordinaryAttribute 

ordinaryAttribute:== dataType ordinaryDirection,,, configure gy; 
ordinary Direction:==/input default, | /bidirectionSetup 


The direction can be user-defined to /input only. If direction is omitted, it is defaulted to 
/bidirect. 


configure:== /configure constraint, 4 


If constraint definition is omitted, all INT and CHAR data types have the constraint definition 
defaulted to /Range. Refer to Table A-1 to get the range values for these data types. 


constraint:== set | range 
set:== /set (value {, value}) 
/set defines the different data types as described in xxxxx. 
range:== /range (rangeValue: rangeValue) 
/range defines the different data types as described in xxxxx. 
value:== range Value| stringText | boolNum 
The value is validated to suit the defined dataType. 
range Value:== pintNum | nintNum | binNum | hexNum | octNum | floatNum 
The range Value is validated to suit the defined dataType. 
bidirectionSetup:== default 
default:== /default (value) 
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default defines default values for the data types with a yes in the default allowed column below. 


Table A-1. Supported data types. Their restrictions. 


Name Size Default Range Set Support Sonera 
allowed | support | support by OB 
IntSmall 8 bits yes yes yes yes If no range or set is given 
for a configurable attribute, 
a default range according to 
the limits for the data types 
size is set. 
IntShort 16 bits yes yes yes yes See comment for IntSmall 
IntLong 32 bits yes yes yes yes See comment for IntSmall 
UlIntSmall byte yes yes yes yes See comment for IntSmall 
UlntShort 16 bits yes yes yes yes See comment for IntSmall 
UlIntLong 32 bits yes yes yes yes See comment for IntSmall 
Float 32 bits yes yes yes yes Length and no of decimals 
required, default 8,2 
Double 64 bits yes yes yes yes Length and no of decimals 
required, default 8,2 
String(n) max 1024 yes no yes yes Always complemented with 
characters in a string length value which 
ObjectParser shall be in C syntax i.e with 
max 256 in an extra byte for terminator. 
ObjectBuilde Default value is limited to 40 
. characters. 
Boolean 8 bits yes no no yes true, false, set or reset 
Bitset32 32 bits yes yes yes yes 
Bitset16 16 bits yes yes yes yes 
struct free no no no NO 
Open array free no no no NO 
Array free no no no NO 
Union free no no no NO 
Enum free no no no NO 
Short Enum free no no no NO 
Char 8 bits yes yes yes NO See comment for IntSmall 
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A.2.4.2 Connections 
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Syntax 
connectionDefinition:== connectionName: Connect connectionType 


connectionName:== identifier 


The connectionName is validated to be a unique name for this object type definition, including 
the inherited names. 


connectionType:== singleConnection | historicalConnection | objectConnection 


singleConnection 
singleConnection:== dataType singleDirection gy, SUPPTESS yyy 
singleDirection:== singleDirectionInput 

If the direction is omitted, it is defaulted to /input. 
singleDirectionInput:== /input singleDefaultOptional,,, 

singleDefaultOptional:== optional | default 

optional:== /optional 


suppress:== /suppress 


objectConnection 
objectConnection:== objectTypeName objectDirection SUPPTESS ony 


The objectTypeName is validated as an already defined object type name. Both abstract and 
configurable object types are valid. Defining the objectDirection is mandatory. 


objectDirection:== objectDirectionInput | objectDirectionOutput 
Defining objectDirection is mandatory. Define as either input or /output. 
objectDirectionInput:==(subscriptionName) /input triggerEvent oy, 


The subscriptionName must be defined by the referenced objectType identified by the 
objectTypeName. 


objectDirectionOutput:== /output 
objectDefaultOptional:== optional 
triggerEvent:== /trigger(eventName) | /trigger Exclusive (evenName) 


The eventName must be defined by the referenced objectType identified by the 
objectTypeName.) 
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A.2.5 Subscriptions 


A.2.6 Commands 
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subscriptionDefinition:== /subscription 
{ subscription} 
endSubscription 


Subscriptions are optional to define. With the subscription definition you define a so called 
Composite Attribute. 


NOTE 


The term subscription is kept for backward compatibility. The appropriate term 
would be CompositeAttribute. Do not mix this with the functionality subscribe 
which is the functionality used to read attributes (including composite attributes) 
through the core system. 


subscription:== subscriptionName description,,;: (subscriptionAttributeList,,,); 
subscriptionName:==identifier 


The subscriptionName must be a unique name for this object type definition, including inherited 
definition names. 


subscriptionAttributeList:== attributeName {, attributeName} 


The attributeNames must all be defined by the objectType, either explicitly or through 
inheritance. The subscriptionAttributeList may contain a maximum of one attribute which is the 
openArray data type. That attribute also has to be placed at the end of the 
subscriptionAttributeList. 


commandDefinition:== /command 
{command} 
endCommand 


Command is an optional field. You can define an optional number of user-defined 
commandDefinition’s with the Command field. 


User-defined commands are merged together with the inherited commands. 


command:== commandName description,,;: (commandParameterDefinition 


op! op 3 


commandName:== identifier 
The commandName must be a unique name for this object type definition. 


The commandName may be defined already by another object type. If so, the number of 
parameters and their names must be identical to be accepted. 


commandParameterDefinition:== commandParameters {, commandParameters } 


The commandParameterDefinition may contain a maximum of one localType or globalType, 
which is or has an openArray data type defined. That data type cannot have the 
parameterDirection output. It must be placed at the end of the commandParameterDefinition. 
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commandParameters:== parameterType parameterDirection,,,, parameterName 


opt 
parameterType:== dataType ° 

ParameterType defines the data type for the configured parameterName. 
parameterDirection:== /input | /output | /bidirect 

If direction is omitted, it is defaulted to /input. 


parameterName:== identifier 


The parameterName is validated to a unique name for this command. 


eventDefinition:== /event 
{event} 

endEvent 

Event declarations are optional. 


event:== eventName description,,;: (eventParameterDefinitiong,;); 
eventName:== identifier 

The eventName is validated as a unique name for this object type definition. 
eventParameterDefinition:== eventParameters {, eventParameters} 
eventParameters:== parameterType parameterName 


The eventParameterDefinition may contain a maximum of one localType or globalType which 
is or has a data type of openArray defined. That data type also has to be placed at the end of the 
eventParameterDefinition. 


commentDefinition:== lineComment | blockComment 
You can place comment definitions anywhere between subdefinitions, but they cannot be 


placed in subdefinitions. 


NOTE 


Do not use an asterisk (*) within block comments. 


A.3 Global Data Type Definition Syntax 
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Global data type definitions are, as the object type definition, described with the Object Type 
Definition Language (OTDL). Global data types are stored in a global data type table which is 
used when all OTDL files are compiled. An OTDL file with global data type definitions cannot 
contain any object type definition. Furthermore, it must be compiled with the ObjectParser 
utility using the qualifier -TYPE. As a result of that processing, the global data type tables are 
updated; that is, a global data type is defined. The syntax for global data types is the same as the 
syntax described for the local data types of an object type definition. 


Comments are allowed. Refer to Section A.2.8, Comments. 
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A.3.1 Global Data Types 


globalDataTypeDefinition:== /globaldef 
{ globaTypeDefinitions } 
endGlobaldef 


globalTypeDefinitions is an optional field. You can define an optional number of global data 
types with this field. 


globalTypeDefinitions:== globalDataTypeName: globalDataTypeDef; 
globalDataTypeName:== globalType 


The globalDataTypeName is validated against the object type definition database to ensure that 
it is a unique data type. 


NOTE 


Globally defined bitset data types CANNOT be inherited or extended with the 
definitions of the unused bits. 


globalDataTypeDef:== globalDataType | bitsetType | struct | union | enum | shortEnum | 
bitset | array | openArray 


globalDataType:== double | float | string | globalType | IntLong | UIntLong | IntShort | 
UIntShort | IntSmall | UIntSmall | Char | Boolean 


The syntax of global data type definitions is the same as for local data type definitions. 


A.4 Value Validation Algorithms 


The max/min value for the POSIX macros (for example FLT_MAX, DBL_MAX) may be 
system-dependent. 


In addition to the max/min checks, the defined precision values are validated to FLT_DIG or 
DBL_DIG. 


A.5 Reserved Keywords 


The reserved keywords are all case-insensitive. 


There are a number of words, reserved by Oracle or by the C++ compilers, which cannot be 
used as attribute or connection names because they will appear as Oracle column names. 
Please refer to Oracle manuals for their description. The OTDL parsing results in an error 
message when a reserved word is used as an attribute or connection name. 


Identifiers are all evaluated to a keyword file, which contains the system’s reserved words. 
This file has default keywords defined. You can add more words to the file and get it customized 
for the system. The name of the file is 


/opt/advant /ObjectBuilder/etc/cokeytable.txt. 


To modify it, talk to your system manager who has the authority to modify the file. 
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Appendix B ObjectBuilder Commands 


B.1 General 


B.1.1 Command Syntax and Conventions 


The syntax used in the description below shows the whole command, although it will suffice to 
enter the first significant characters in the command. For example, enter O for Select Operation 
design. All commands are case-insensitive, i.e., uppercase and lowercase are insignificant. 


If you give a command without all the required parameters, a prompt will ask you for those 
parameters. For example, the command ADD fileName objectTypeName can be given as: 


TYPE DEFINITION>add 
fileName: xxxxxxx <CR> 


objectTypeName: yyyyyyy <CR> 


B.1.2 General Commands 


HELP 


You can request HELP at any time. A list of commands available in the current situation is 
displayed. 


LIST 
A context-sensitive list is available in all parts of the ObjectBuilder. You can request the list in 
two ways: 


° LIST always lists the default setting, which is described in subsequent chapters. 
The -OUTPUT qualifier, described below, can be used to redirect the list to a file. 


° LIST -qualifierList- overrides the default and lists according to the qualifiers specified. 
If several qualifiers are specified, all the default settings are discarded. Only the - 
OUTPUT qualifier can be used without overriding the default setting. The qualifiers 
available in three modes: 


— The General mode, which is always available. 
— The Object Type mode, which is available whenever an object type is selected. 


— The Object Handler mode, which is available whenever an object handler is 
selected. 
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General mode qualifiers are: 


OUTPUT=fileName, which redirects the list to a file instead of the TTY. You can 
use this qualifier with any other qualifiers. 


TYPE, which lists the name and description of all object types. 

COMPILED, which requires -TYPE and lists the object types compiled. 

LIB, which lists all defined external libraries. 

HANDLER, which lists all defined object handlers. 

ACTIVE, which requires -HANDLER and lists all active (running) object handlers. 


Object Type Mode qualifiers are: 


ASSIGNED, which requires LIB and lists all external libraries assigned to the 
selected object type. 


OPERATION, which lists all operations (Normal and Command) defined for the 
selected object type. 


NORMAL, which requires OPERATION and lists all Normal Operations for the 
selected object type. 


COMMAND, which requires OPERATION and lists all Command Operations for 
the selected object type. 

COMPILED, which requires either -TYPE (see description above) or 
OPERATION. If you use OPERATION, only the compiled operations are listed. 
Use the NORMAL and COMMAND qualifiers to specify compiled Normal or 
Command Operations. 


Object Handler mode qualifiers are: 


EXIT 


CONFIGURATION, which requires HANDLER and lists the configuration of the 
selected object handler. 


EXIT always returns you to the previous level in ObjectBuilder. EXIT terminates 
ObjectBuilder at the top level. 


QUIT 


QUIT always terminates ObjectBuilder. 


The object type is defined in OTDL syntax. Text files with OTDL descriptions are created and 
maintained with any available text editor. 
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After start-up, ObjectBuilder returns the OBJECT BUILDER? prompt. Enter any of the 
following commands, representing the top level of the tool, at this prompt: 


TYPE displays the TYPE DEFINITION> prompt. 

LIBRARY displays the LIBRARY DECLARATION? prompt. 

OPERATION displays the OPERATION DESIGN? prompt. 

BUILD displays the BUILD> prompt. 

LIST (See Section B.1.2, General Commands, General Commands.) Default is -TYPE. 


HELP displays a list of available commands. (See Section B.1.2, General Commands, 
General Commands.) 


EXIT terminates ObjectBuilder. 
QUIT terminates ObjectBuilder. 


B.3 Object Type Definition 


After selection Object Type Definition, enter any of the following commands at the TYPE 
DEFINITION > prompt: 


ADD fileName objectTypeName adds a new definition to the tool and displays the TYPE 
DEFINITION: objectTypeName> prompt. ADD automatically selects the object type 
(see SELECT). 


SELECT objectTypeName selects a defined object type to operate on and displays the 
TYPE DEFINITION: objectTypeName> prompt. 


LIST (See Section B.1.2, General Commands, General Commands.) Default is -TYPE. 


HELP displays a list of available commands. (See Section B.1.2, General Commands, 
General Commands.) 


EXIT leaves TYPE DEFINITION? and returns to OBJECT BUILDER>. 
QUIT terminates ObjectBuilder. 


Enter any of the following commands at the TYPE DEFINITION: objectTypeName> prompt: 
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COMPILE [-LIST [=fileName]] compiles the object type definition. Use the qualifier 
-LIST to have the compiler generate a list file. If no list file is specified, the file name 
objectTypeName.LIS is used. 


GET fileName [-FORCE] retrieves the selected type definition from the tool and stores it 
as fileName. If the file already exists, the -FORCE qualifier overwrites it. 


DELETE deletes all definitions for the selected object type. 
ASSIGN aliasLibraryName assigns a library to the object type. 


DEASSIGN aliasLibraryName deassigns a library according to the aliasLibrary Name 
from the object type. 


ADD fileName objectTypeName (See above.) 
SELECT objectTypeName (See above.) 
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LIST (See Section B.1.2, General Commands, General Commands.) Default is -TYPE. 
Object type mode qualifiers are selectable. 


HELP (See above.) 


EXIT leaves TYPE DEFINITION: objectTypeName> and returns to 
OBJECT BUILDER> 


QUIT terminates ObjectBuilder. 


PARAMETER EXPLANATIONS (Type Definition) 


fileName: Name of the source file or of a list file according to POSIX standard. 
objectTypeName: A unique object type name of the format name. 


aliasLibraryName: A name of format name identifying a library declared for the system 
as described in Section B.4, Library declaration, Library Declaration. 


The type definition is now available for Normal and Command Operation design. 


B.4 Library declaration 


After selection Library Declaration, enter any of the following commands at the LIBRARY 
DECLARATION > prompt: 


ADD [-first | -before= aliasLibraryName | -after = aliasLibraryName] fileName 
aliasLibraryName path description adds an interface file to an external library to 
ObjectBuilder. You can specify the linking order of the libraries by entering the -first - 
before and -after switches. If no switches are specified, the library is inserted last. 


GET fileName aliasLibraryName [-FORCE] retrieves an interface file from 
ObjectBuilder. If the file already exists, the -FORCE qualifier overwrites it. 


MODIFY [-PATH[=path]][-DESCRIPTION[=description]] alias LibraryName 
modifies the library path, library description or both. The tool will prompt for a description 
and/or a path to the object library if only the qualifier(s) is/are given. 


DELETE aliasLibraryName deletes a declared library. This is allowed only if the library 
is not assigned to any object type. 


LIST (SeeSection B.1.2, General Commands, General Commands.) Default is -LIB. 


HELP displays a list of available commands. (See Section B.1.2, General Commands, 
General Commands.) 


EXIT leaves LIBRARY DECLARATION? and returns to OBJECT BUILDER>. 
QUIT terminates ObjectBuilder. 


PARAMETER EXPLANATIONS (Library Declaration) 
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fileName: Name of the source file or of a list file according to POSIX standard. 
aliasLibraryName: A unique alias name (Name format). 


path: A file description, according to POSIX standard, of the library or object file to 
include when the object handler(s) are linked. 


description: A text describing the library/routine to include. 
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B.5 Operation Design 


B.5.1 Top level 


3BSE 001 012R0501 


After selection Operation Design, enter any of the following commands at the OPERATION 
DESIGN> prompt: 


° SELECT objectTypeName selects a defined object type to operate on and displays the 
OPERATION DESIGN: objectTypeName> prompt. 


° LIST (See Section B.1.2, General Commands, General Commands.) Default is -TYPE - 
COMPILED. 


° HELP displays a list of available commands (see Section B.1.2, General Commands, 
General Commands). 


° EXIT leaves OPERATION DESIGN? and returns to OBJECT BUILDER>. 
° QUIT terminates ObjectBuilder. 


Enter any of the following commands at the OPERATION DESIGN: objectTypeName> 
prompt: 


° NORMAL selects Normal Operation design for the object type and displays the 
NORMAL DESIGN: objectTypeName> prompt. 


° COMMAND selects Command Operation design for the object type and displays the 
COMMAND DESIGN: objectTypeName> prompt. 


° USERDEF selects user definition design for the object type and displays the 
USERDEF DESIGN: objectTypeName> prompt. 


° LASTOP select Last Operation design for the object type and displays the 
LASTOPERATION DESIGN: objectTypeName> prompt. 


° SELECT objectTypeName (See above.) 


° LIST (See Section B.1.2, General Commands, General Commands.) Default is - 
OPERATION. Object type mode qualifiers are available. 


° HELP (See above.) 


° EXIT leaves OPERATION DESIGN: objectTypeName> and returns to 
OBJECT BUILDER>. 


° QUIT terminates ObjectBuilder. 
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B.5.2 Normal Operation 
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After selection Normal Operation, enter any of the following commands at the NORMAL 
DESIGN:objectTypeName> prompt: 


° ADD fileName normalOperationNumber description adds a new Normal Operation to 
the tool. 


° COMPILE [-LIST=[fileName]] normalOperationNumber compiles the Normal 
Operation source code. The -LIST[=fileName] qualifier makes the compiler generate a 
list file. If you use -LIST without the file name, the list is reported to 
<ObjectTypeName><normalOperationNumber>.LIS. 


° GET fileName normalOperationNumber [-FORCE] retrieves a Normal Operation from 
the tool. If the file already exists, the -FORCE qualifier overwrites it. 


° DELETE normalOperationNumber deletes a Normal Operation for the selected object 
type. 


° SELECT objectTypeName selects a defined object type to operate on and displays the 
NORMAL DESIGN: objectTypeName> prompt. 


° LIST (See Section B.1.2, General Commands, General Commands.) Default is - 
OPERATION -NORMAL. Object type mode qualifiers are available. 


° HELP displays a list of available commands (see Section B.1.2, General Commands 
General Commands). 


° EXIT leaves NORMAL DESIGN:objectTypeName> and returns to 
OPERATION DESIGN: objectTypeName>. 


° QUIT terminates ObjectBuilder. 
PARAMETER EXPLANATIONS (Normal Operation Design) 


° fileName: Name of a source file or of a list file according to POSIX standard. 
° ObjectTypeName: A unique object type name (Name format). 
° normalOperationNumber: Number of the Normal Operation, 1-10. 


To make testing the new object type easier, ObjectBuilder supports the detection of as many 
errors as possible during compilation. The Normal Operation source file is compiled with the 
appropriate compiler until it is error-free. Checks for errors are made to ensure that: 


° Only attributes and connections defined at object type design can be accessed. 


° The same type of tests are performed on attributes and connections as are performed on 
other types definable in the language. 


° Connections and input attributes are impossible to assign values to. 
° The syntax of commands are checked. 
° Commands are allowed only toward output object connections. 


Compile the Normal Operation source file with the ObjectParser until it is error-free, then add it 
the Object Builder and compile it using the ObjectBuilder commands described above. 
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B.5.3 Command Operation 
After selection Command Operation, enter any of the following commands at the COMMAND 
DESIGN: objectTypeName> prompt: 


° ADD fileName commandOperationName description adds a new Command Operation to 
the tool. 


° COMPILE [-LIST=[fileName]] commandOperationName compiles the Command 
Operation source code. The -LIST[=fileName] qualifier causes the compiler to generate a 
compiler list file. If you use -LIST without the file name, the list is reported to 
<ObjectTypeName><commandOperationName>.LIS. 


° GET fileName commandOperationName [-FORCE] retrieves a Command Operation 
from the tool. If the file already exists, the -FORCE qualifier will overwrite it. 


° DELETE commandOperationName deletes a Command Operation for the selected 
object type. 


° SELECT objectTypeName selects a defined object type to operate on and displays the 
COMMAND DESIGN: objectTypeName> prompt. 


° LIST (See Section B.1.2, General Commands, General Commands.) Default is 
-OPERATION -COMMAND. Object type mode qualifiers are available. 


° HELP displays a list of available commands (see Section B.1.2, General Commands, 
General Commands). 


° EXIT leaves COMMAND DESIGN: objectTypeName> and returns to OPERATION 
DESIGN: objectTypeName>. 


° QUIT terminates ObjectBuilder. 
PARAMETER EXPLANATIONS (Command Operation Design) 


° fileName: Name of a source file or of a list file according to POSIX standard. 
° objectTypeName: A unique object type name. Name format. 


° commandOperationName: Name of the Command Operation. A unique (within the 
Command Operations) name in name format. 


To make testing the new object type easier, ObjectBuilder supports the detection of as many 
errors as possible during compilation. The Command Operation source file is compiled with the 
appropriate compiler until it is error-free. Checks for errors are made to ensure that: 


° Only attributes and connections defined at object type design can be accessed. 


° The same type of tests are performed on attributes and connections as are performed on 
other types definable in the language. 


° Connections and input attributes are impossible to assign values to. 
° The syntax of commands are checked. 


° Commands are allowed only toward output object connections. 
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B.5.4 User Defined 
After selection User Definition, enter any of the following commands at the USERDEF 
DESIGN: objectTypeName> prompt: 


° ADD [-HEADER | -IMPLEMENTATION ] fileName adds a new user-definition to the 
tool. 


° COMPILE [-LIST=[fileName]] compiles the user-defined source code. 
The -LIST[=fileName] qualifier causes the compiler to generate a list file. If you use - 
LIST without the file name, the list is reported to <ObjectTypeName>.LIS. 


° GET [-HEADER | - IMPLEMENTATION] fileName [-FORCE] retrieves a user 
definition from the tool. If the file already exists, the -FORCE qualifier overwrites it. 


° DELETE deletes the user definition for the selected object type. 


° SELECT objectTypeName selects a defined object type to operate on and displays the 
USERDEF DESIGN: objectTypeName> prompt. 


° LIST Lists whether the user defined operation is implemented, or not. 
° HELP displays a list of available commands. 


° EXIT leaves USERDEF DESIGN: objectTypeName> and retums to 
OPERATION DESIGN: objectTypeName>. 


° QUIT terminates ObjectBuilder. 
PARAMETER EXPLANATIONS (Normal Operation Design) 
° fileName: Name of a source file or of a list file according to POSIX standard. 


° ObjectTypeName: A unique object type name. Name format. 


B.5.5 Last Operation 
After selection Last Operation, enter any of the following commands at the 
LASTOPERATION DESIGN: objectTypeName> prompt: 
° ADD fileName adds the last operation to the tool. 
° COMPILE compiles the last operation source code. 
° GET [-FORCE] fileName retrieves the last operation from the tool. 
° DELETE deletes the last operation for the selected object type. 


° SELECT objectTypeName selects a defined object type to operate on and displays the 
LASTOPERATION DESIGN: objectTypeName> prompt. 


° LIST Lists whether the last operation is implemented, or not. 
° HELP displays a list of available commands. 


° EXIT leaves LASTOPERATION DESIGN:objectTypeName> and returns to 
OPERATION DESIGN: objectTypeName>. 


° QUIT terminates ObjectBuilder. 
PARAMETER EXPLANATIONS (Normal Operation Design) 


° fileName: Name of a source file or of a list file according to POSIX standard. 


° ObjectTypeName: A unique object type name. Name format. 
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After selection Build, enter any of the following commands at the BUILD> prompt: 


ADD objectHandlerName defines and selects an object handler. Description and 
priority configuration parameters are prompted for. Displays the 
BUILD: objectHandlerName> prompt. 


SELECT objectHandlerName selects an object handler to operate on. Displays the 
BUILD: objectHandlerName> prompt. 


LIST (See Section B.1.2, General Commands, General Commands.) Default is - 
HANDLER. 


HELP displays a list of available commands (see Section B.1.2, General Commands, 
General Commands). 


EXIT leaves BUILD> and returns to OBJECT BUILDER>. 
QUIT terminates ObjectBuilder. 


Enter any of the following commands at the BUILD: objectHandlerName> prompt: 


START starts the execution of the selected object handler. 
STOP stops the execution of the selected object handler. 
ASSIGN objectTypeName adds object types to the selected object handler. 


DEASSIGN objectTypeName deletes object types in the selected object handler. 
Execution must stop. 


NOTE 


Before you deassign and delete an object type you need to remove all instances. If 
you want to configure them again and with the same identities you have to do the 
following: Dump them into a text file using ObjectUtil. After assigning the 
corrected object type and rebuilding, copy the context file stored under /tmp 
according to a warning message that you will receive, to it’s proper position. Now 
you can configure the instances again using ObjectUtil. 


BUILD compiles the common software for the included object types and links the selected 
object handler. 


DELETE deletes the object handler definition. 
ADD objectHandlerName (See above.) 
SELECT objectHandlerName (See above.) 


ENVIRONMENT enters environment variable definition and displays the 
ENVIRONMENT DEFINITION: objectHandlerName> prompt. 


LIST (See Section B.1.2, General Commands, General Commands.) Default is - 
HANDLER 
-CONFIGURATION. Object Handler mode qualifiers are available. 


HELP (See above.) 


EXIT leaves BUILD: objectHandlerName> and returns to 
OBJECT BUILDER>. 
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QUIT terminates ObjectBuilder. 


PARAMETER EXPLANATIONS (Add) 


description: A description of the object handler. 


priority: A value 1-10 where | is low, 5 is normal and 10 is high priority. This is scaled to 
different computer platforms. (This parameter for future use) 


B.6.1 Environment Definition 
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After selection Environment, enter any of the following commands at the ENVIRONMENT 
DEFINITION: objectHandlerName> prompt: 


ADD fileName adds a new environment file to the selected object handler. 
DELETE deletes the environment file from the selected object handler. 
GET [-FORCE] fileName retrieves an environment file from the tool. 
LIST Lists the contents of the environment file. 

HELP displays a list of available commands. 


EXIT leaves ENVIRONMENT DEFINITION: objectHandlerName> and returns to 
BUILD: objectHandlerName>. 


QUIT terminates ObjectBuilder. 


PARAMETER EXPLANATIONS (Normal Operation Design) 


fileName: Name of a source file or of a list file according to POSIX standard. 
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Appendix C ObjectParser Commands 


C.1 General 


You use the ObjectParser to compile OTDL and Operation files. You give the command 
directly, and do not have to add, select and delete any files. Once the compilations are 
successful, you enter the files to the ObjectBuilder. The ObjectBuilder will store the files in a 
library together with all other User Object Types. 


C.2 Compiling OTDL files 


° ObjectParser -TYPE [-LIST[= listFileName]] fileName [-NINH] [-MODE=mode] 


fileName - Name of the source file according to POSIX standard. 
LIST - Defines a name of a list file “listFileName” according to POSIX standard. 


NINH - No INHerited flag reveals whether any inheritance is to be applied to the 
object type. 


MODE - Defines the running mode for the ObjectParser. The mode options are as 
follows. 


extparse: The OTDL file is compiled and the object type is made available in the 
common database. The default is extparse. 


trace: In addition to the parse mode, this mode generates extra parse descriptions of 
ObjectParser states. 


parse: The OTDL file is checked for syntactic errors only. 


syntax: The OTDL file is parsed and checked for syntax errors. (In this mode 
connected object types does not have to exist). 


This compilation includes the OTDL file and reports errors, if any. Errors are reported to the 
screen if no list file is given, or to the list file. If you use the qualifier -LIST without specifying 
a file, the list is reported to fileName.LIS. 
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NOTE 


When you intend to create User Objects, always use the -mode=parse qualifier 
during your OTDL compilations. When you use the OTDL to describe an 
application implemented with the Core System Services, which is normally done 
only by ABB Development centers, use the qualifier -mode=extparse which is 
the default. 
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C.3 Compiling Operations 
Once you have edited the operation source file to a point where it can be compiled, use the 
following commands to compile it. 
° For Normal Operations: 
ObjectParser -NORMAL [-LIST[=listFileName]] objectTypeName fileName 
° For Command Operations: 


ObjectParser -COMMAND [-LIST[=listF ile Name]] objectTypeName commandName 
fileName 


This compilation includes the operation file and reports errors, if any exist. No output, except 
for the error messages, is produced. The errors are reported to the screen or to the optional list 
file. If the -LIST qualifier is used without a file name, the list file is reported to 
ObjectParser.lis. When the operation file is error-free, you can proceed to compile the 
operation using ObjectBuilder. 


PARAMETER EXPLANATIONS 


° fileName, listFileName: Name of the source file or of a list file according to POSIX 
standard. 


° objectTypeName: A unique object type name. Name format. 


° commandName: Name of the Command Operation. A unique (within the Command 
Operations) name in name format. 
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Appendix D ObjectUtil Commands 


D.1 Introduction 


D.1.1 Service Summary 


ObjectUtil provides a number of basic services for the Object Handling database. 
The utility provides services to handle: 


global data types 

activation and deactivation of attribute shadowing to disk 

dump of object instances into text files 

population of object instances from text dumps 

removal of an object type compiled into the database through ObjectParser 
selecting method to read input connections 


load balancing 


CAUTION 
The ObjectUtil is an off-line utility requiring restart of the affected object handler 
before changes affect the execution. The population of instances shall only be 
done with the object handler stopped. 


D.1.2 Global Data Types 


ObjectUtil provides services to maintain the database. If global data types have been defined but 
are later made obsolete, you can identify these global data types and remove them with 
ObjectUtil. 


D.1.3 Activation and Deactivation of Disk Shadowing 


By default, when a User Object attribute is updated, the corresponding attribute information in 
the database table is also updated. . For some object types, this is not required or perhaps not 
even desired as it puts an additional load on the system. 


ObjectUtil provides commands to activate or deactivate this disk shadowing for all objects of an 
object type or just for one specific instance at a time. 
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D.1.4 Dump and Load of Object Instances to/from Text Files 


D.1.4.1 Introduction 


You are often required to load the configuration of object instances from text files. For instance, 
when: 


° you move pre-configured object instances from an in-house system into a plant. 


° the customer supplies configuration data for all objects in the system. This text information 
can be reformatted to suit an appropriate text format. 


° you are upgrading from one IMS version to another, the object database information needs 
to be moved into the new system. 


User Object instances can be described in a source code format. The source code can either be 
generated automatically from existing instances, or manually created in a text editor. The proce- 
dure of dumping existing instances into text files and loading them again is described below. An 
example of the source code is provided. 


D.1.4.2 Dump and Load of Object Instances 


You dump all instances of a User Object type using the command dumpIT: 
Dump: 
$ ObjectUtil dumpIT <objectTypeName> <fileName> 
You load instances using the command popIT: 
Load (populate): 


$ ObjectUtil popIT <fileName> 


NOTE 


You can load all object types from one text file if you merge all text files into one. 


D.1.4.3 Validation Checks 


During the loading of source code the following checks are made: 
e the object names are legal 
¢ attribute values are within the specified ranges or sets 


* constant values given to single connections values are within the specified ranges or sets. 


D.1.4.4 Manual Creation of Source File 
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Use an existing source code file instead of creating a new. If you want to create a large number 
of objects, the most convenient method is to dump one object and then use the editor’s cut and 
paste methods to create copies of it. You have to change at least the object name and all connec- 
tions to other objects, but many attribute defaults can be the same. An example is provided in 
Section D.1.4.6 Example of a User Object Source Code Dump. 
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D.1.4.5 Syntax Description 
dump_spec: 
dumpSpecDefinition: 
objectTypesDefinition: 
object_types: 
object_type: 
objectsDefinition: 


objects: 


object: 


execParams: 
execParams_vl: 
terminalsDefinition: 
terminals: 


terminal: 
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dumpSpecDefinition 
START objectTypesDefinition END 
/* Empty */ 

object_types 

object_type 
| object_types object_type 
OBJECT_TYPE NAME 
/* Empty */ 
| 

objects 

object 
| objects object 
OBJECT NAME 

execParams terminalsDefinition 
END_OBJECT 
execParams_vl 
execParams_vl1 ORACLE SHADOW DATA 
START_TIME DATA 
NORMAL_OPERATION DATA 
/* Empty */ 

terminals 

terminal 

terminals terminal 
ATTRIBUTE NAME DATA 
SINGLE_CONN NAME 
CONN_TYPE DATA 
CONSTANT_VALUE DATA 
CONN_OBJECT DATA 
ATTRIBUTE DATA 
SUPPRESS DATA 
OPTIONAL DATA 
OPTIONAL_USED DATA 
END_SINGLE_CONN 
| OBJECT_CONN NAME 
CONN_OBJECT DATA 
SUPPRESS DATA 
OPTIONAL DATA 
OPTIONAL_USED DATA 
TRIGGER DATA 
EVENT_NAME DATA 
END_OBJECT_CONN 
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Table D-1. Description of the different components 


Identifier name 


Explanation 


Values 


ObjectType Object type name. Identifies the object type | An object type name may be up to 
that the object definition that follows 20 characters. It must start with a letter. 
belongs to. See the OTDL description. 
Object Object name. Uniquely identifies the object. | An object name may be up to 20 characters. 
Must be unique in the IMS system. It is 
recommended, but not checked, that it is 
unique in the whole system. 
StartTime A text string that describes the execution of | When you define this text string, consider the 
the object instances. following: 
A “%” character in the beginning of the text 
means that no cyclic or scheduled execution 
shall take place. 
“%*” is default if no pre-defined execution shall 
be defined. 
Use the Object Configuration display to 
configure the requested scheduling and then 
view the resulting text string in the text field or 
dump the resulting instance to a text file. 
NormalOp An object type can have from one up to ten | 1-10 


different implementations of normal 
operations. Configure which one to execute 
with this parameter. 


(Note that the object type must have the 
corresponding normal operation implemented). 


OracleShadow 


If OracleShadow is active, all attribute 
updates are automatically updated in the 
IMS database as soon as any change 
occurs. 


Active = ‘Y’ 
Not active = ‘N’ 
Default = ‘Y’ 


AttributeName 


Identifies the attribute that the attribute 
value shall be given to. 


An attribute name may be up to 20 characters. It 
must start with a letter. See the OTDL 
description or the Object Configuration display 
for a list of possible attribute names. 


AttributeData 


Attribute value 


Depends on the attribute data type. Values are 
checked towards defined ranges, sets and data 
formats. 


SingleConn 


Identifies the single connection 


A connection name may be up to 20 characters. 
It must start with a letter. See the OTDL 
description or the Object Configuration display 
for a list of possible connection names. 


ConnType 


Single connection type 


“object” = connected to an object 
“constant” = a constant value is configured 
“none” = not configured 
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Table D-1. Description of the different components (Continued) 


Identifier name Explanation Values 

ConstantValue | Constant value Depends on the attribute data type. Values are 
checked towards defined ranges, sets and data 
formats. 

ConnObject Name of connected object. See object above. Must be the name of an 
existing object. (Checked when the object is 
started.) 

Attribute Name of attribute of connected object. See attribute name above. The attribute name 
must exist for that object type. 

Suppress, See chapter 3 of the Object Type Builder _| Active=’Y’ 

Optional, User's Guide for details on these qualifiers. | Not active=’N’ 

OptionalUsed Default=’N’ 

ObjectConn Identifies the object connection A connection name may be up to 20 characters. 
It must start with a letter. See the OTDL 
description or the Object Configuration display 
for a list of possible connection names. 

ConnObject Name of connected object. See object above. Must be the name of an 
existing object. (Checked when the object is 
started.) 

Suppress, See chapter 3 of the Object Type Builder _| Active=’Y’ 

Optional, User's Guide for details on these qualifiers. | \iot active=’N’ 

OptionalUsed Default=’N’ 

EventName Name of event of connected object. If An event name may be up to 20 characters. 

trigger is active, this event willbe requested | The event name must exist for that object type. 
for and activate the object on event. 
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D.1.4.6 Example of a User Object Source Code Dump 


The following example shows the source code of an instance with three attributes, one single con- 


nection and one object connection. It will execute once every minute. 


START 
ObjectType 
Object 
StartTime 
NormalOp 
OracleShadow 
Attribute 
Attribute 
Attribute 
ObjectConn 
ConnObject 
Suppress 
Optional 
OptionalUsed 
Trigger 
EventName 
endObjectConn 
SingleConn 
ConnType 
ConstantValue 
ConnObject 
Attribute 
Suppress 
Optional 
OptionalUsed 
endSingleConn 
endObject 
ndObjectTyp 
END 


usercalcobjconn 

UCALCOBJCONN_1 

“[%60] (*) / (*) / (*) (*) : (*) /PAR=[DEFAULT] ” 
il 

wy” 

DESCRIPTION “Example Object™ 
STATUS 0 

value 0 

Obj1 

SATO LL 21 

“N” 

“nN” 

wy” 

“N” 


wow 


Ob j2 
“object” 
0 
“AIC71_2" 
“VALUE” 
WN” 

YN” 


ww 


D.1.5 Removal of an Object Type Entered with ObjectParser 


When you use the ObjectParser with the qualifier mode=extparse, the Object Type Definition 
will be stored in the Object Type database. To delete it (for example when you want to redefine 
the Object Type) use ObjectUtil and the command rumTT. 
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D.1.6 Selecting Method to Read Input Connections 


The default method to read input connections keeps all references to the input objects between 
each execution of the object. This method is preferred because of its high performance. If you 
run out of memory on the RTA board, you can use another method. This method sets up all 
references, reads the data and then removes the references each time the object executes. 
Therefore it requires less memory. 


The methods can be selected per object type. To select the method you use the ‘ObjectUtil’ tool: 
$ ObjectUtil subscribeTT <objectTypeName> (default) 
$ ObjectUtil submitTT <objectTypeName> 


This method can only be used when the object handler that manages the object types is stopped. 


D.1.7 Load Balancing 


If many User Objects execute simultaneously the amount of data requests from them to the 
controllers may become too large resulting in overload situations and failure to read data 
properly. A load balance function is provided to prevent overloads. You can configure how many 
User Objects that may request for data simultaneously. 


Use ObjectUtil> queueOH <Obj.Handler name> <max> <min> 


where max=3 and min=1 as default. This means that 3 (max) objects are performing a read 
request of their connections simultaneously. When only | (min) of these three objects hasn’t 
received its request, then the object handler treats another 2 objects to become 3 ongoing 
requests again. 


D.2 Starting ObjectUtil 
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The ObjectUtil utility is activated from the main AdvaInform menu by selecting Object 
Handling and then the sub menu Object Handlers. 


— Advant Station 500 Information Management Station | ° | 
File Station AdvaBuild Advalnform Session Settings Help 
Object Handling + Obi "| 7 
ject Configuration 
Reports Object_Status 
Object Handlers 


Figure D-1. Selecting the Object Configuration and Object Handler facilities 


The ObjectUtil is a privileged utility. You must start the IMSmenu as the user imsmgr for access 
to it. The ObjectHandlers selection opens up a terminal window. ObjectUtil is an interactive 
tool. Just enter ObjectUtil and You will be prompted for additional commands: 


$ ObjectUtil 


ObjectUtil x.y-z> <interactive commands> 
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D.3 Command Syntax 
exit: 
help: 
IsDT [-full]: 


rmDT <global datatype name>: 
oralTallon <objectTypeName>: 
oral Talloff <objectTypeName>: 


oralTon <objectName>: 


oral Toff <objectName>: 

dumpIT <objectTypeName> <fileName>: 
popIT <fileName>: 

IsTT: 


rmTT <object type name>: 


Logs off the data base and exits the program. 
Provides brief information about all commands. 


Lists names of all global data types and indicates 
whether they are used or not. Unused data types 
can be deleted. If -full switch is given, the data 
type definition is also listed. 


Removes the data type with the given name. The 
data type may not be used by any object type. 


Activates disk shadowing for all object instances 
of the described type. 


Deactivates disk shadowing for all object 
instances of the described type. 


Activates disk shadowing for one object instance. 


Deactivates disk shadowing for one object 
instance. 


Dumps all object instances for the object type into 
a text file. 


Loads all object instances for the object type from 
a text file. 


Lists the names of all object type names entered 
in the database. 


Removes an object type. This is done whenever 
an object type which has already been parsed and 
found error-free from the ObjectParser 
mode=extparse shall be parsed again. An error 
free parsing with that mode qualifier means that 
the object type definition is stored in the Object 
Type database. The old object type definition 
must be deleted before the parsed, error-free 
definition can take its place. 


NOTE 


Use this command only when the object types are entered to the Object Type 
Database by the ObjectParser. In all other cases You must delete the Object Type 


using the ObjectBuilder utility. 
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D.4 Examples 


The following is made within the ObjectBuilder terminal window: 


SObjectUtil 


ObjectUtil x.y-z> l1sTT 
BasicObject 

DCSObject 

BlankObject 

Al 

AO 

DI 

DO 


MyObjectType 


Enter the program and log-on the 
Oracle data base. 


List all object types. 


ObjectUtil x.y-z> rmTT myobjecttype Delete the object type 


ObjectUtil x.y-z> lsDT -full 
USED: TdName 


String (21) 


USED: TdDescription 
String (29) 


ObjectUtil x.y-z> exit 


MyObjectType. 


Exit the program. 
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Appendix E Object Handlers Commands 


E.1 Introduction 


The Object Handlers utility contains a number of basic services that makes it possible to 
manage the run time environment, that is the Object handlers, and to transfer Object Types with 
their run time environment between Advant Stations. 


The services provided are: 

° List all defined object handlers. 
° Start an objecthandler 

° Stop an objecthandler 


° Dump an object type and it’s run time environment for transfer to another node 
° Load an object handler and all it’s definitions into an IMS node. 


° Removes a transferred object handler and all it’s definitions from the IMS node. 


E.2 Starting the ObjectHandlers Utility 


The ObjectHandlers is an interactive tool. You activate it in the Object Builder terminal window 
by giving the command. 


$ ObjectHandlers 
ObjectHandlers x.y-z> <interactive commands> 
As an alternative, give a command directly on the command line: 


$ ObjectHandlers start MyOwnHandler 


E.3 Command Syntax 
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exit: Logs off the data base and exits the utility. 

help: Gives brief information about all commands. 

list: Lists the names of all object handlers and their current state. The state can be: 
STARTED, starting, stopped, stopping 

start <object handler name>: Start the object handler with that name. 


stop <object handler name>: Stop the object handler with that name. 


dump <object handler name>: Dump all information about an object handler and all its 
supported object types into a transfer file for later transfer to another IMS node. 


load <object handler name>: Load all information about an object handler and all its supported 
object types from the specified file for installation into the IMS node. The file is named <object 
handler name>TRANSFER.tar and must reside under the current directory. 


unload <object handler name>: Remove all information about an object handler and all its 
supported object types from the IMS node. 
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E.4 Examples 


Load is explained in Chapter 3, Configuration and Application Building. 


START 


To start an object handler called averagehandler do as follows. Start by activating the Object 
Builder terminal window. Then perform the following steps: 


$ ObjectHandlers 
ObjectHandlerUtil x.y-z> 
NAME Configured_State 
averagehandler Stopped 


<ENTER> 


list 
Actual_State ProcessID 
Stopped 0 


ObjectHandlerUtil x.y-z> start averagehandler 
ObjectHandlerUtil x.y-z> exit 


As a verification of the result, the state shall become Starting and then STARTED and the 
ProcessId shall become non zero also for the started object handler. 


STOP 


To shut down an object handler called averagehandler do as follows. Start by activating the 
Object Builder terminal window. Then perform the following steps: 


$ ObjectHandlers <ENTER> 


ObjectHandlerUtil x.y-z> list 

NAME Configured_State Actual_State ProcessID 
averagehandler STARTED STARTED 476 
ObjectHandlerUtil x.y-z> stop averagehandler 
ObjectHandlerUtil x.y-z> exit 


As a verification of the result, the state shall become Stopping and then Stopped and the 
ProcessId shall become zero for the stopped object handler. To see those results you have to 


enter the list command e.g as: 


$ ObjectHandlers list <ENTER> 


NAME Configured_State 
averagehandler Stopped 
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Actual_State ProcessID 
Stopped 0 


3BSE 001 012R0501 


AdvaBuild® Object Type Builder User’s Guide 
Section F.1 General 


Appendix F Object Type Examples 


F.1 General 


This chapter describes six examples. First there are two traditional examples: AverageObj and 
Outputsender. Secondly, three examples showing how to use the User API from User Objects 
are provided. In addition to these examples three object types included in the AdvaInform 
Object Handling are provided as source code. You are free to modify them for your own 
purposes. These three object types are: 


° coRTM Run Time Measurement 
° coExecutor Object that executes any program or script in the IMS 


° coBasicCalc Object that performs a number of different calculations on 2 to 10 input 
values. Examples on calculations: sum, average. 


The Advalnform Object Type Reference Manual contains a complete description of these object 
types. The source code for all the object types is provided under 
/opt/advant/ObjectBuilder/examples. 


F.2 AverageObj Example (Master specific) 


This example shows how object connections can be used between different User Objects. The 
Basic Object AI is also a User Object. 


The AverageObj example is almost identical with the Average example. The main difference is 
that the Average object type has single connections as input while the AverageObj has object 
connections. Study the normal operation file to see how single connections, mandatory and 
optional, are accessed. The Master specific features are underlined. 


F.2.1 Required Functionality: An Average Calculation 


The functionality of the AverageObj object is as follows: 


° The object type reads three compulsory and one optional analog input object values, 
calculates an average value, and compares the average with an upper and a lower alarm 
limit. The result is stored in an attribute called Value. Alarm status bits are refreshed 
according to the current limit check situation. Events are generated when the alarm limits 
are transgressed and when the object returns into normal state again. 


° Three commands are supported. One is a user-defined command to change the alarm limits 
called ChangeLimit. The other two are the compulsory commands for support of alarm 
treatment: Acknowledge and Order. 


° Two events to signal the individual transgression of the alarm limits and one that signals 
any transgression to any other object that subscribes to such triggering, are defined. 
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Lets brake the requirements down into User Object terminology: Normal Operation, Input, 
Output, Commands, Subscriptions, Events: 
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Algorithm (Normal Operation) 


Calculate the average of a number of input temperatures and verify that the result is within 
certain limits (Normal Operation). 


Input 


The measured value of four different Analog Inputs (Connections) of which one is 
optional and one upper and one lower limit (Attributes) 


Output 
The calculated average value (Attributes) and a status (Attributes). 
Events 
When the value is outside a limit and when it returns back into normal state. 
Commands 
ChangeLimit: A command to change the limits (Command Operation) 


Order: To handle the information from Alarm lists that an unacknowledged alarm 
exists 


Acknowledge: To handle acknowledge from Alarm Lists. 
Subscriptions: 


The value and the status are convenient to address as one entity from subscribers. Thus, a 
subscription that packs them together in a list is defined. 


Input Definitions Application code 
Al ——>} ean 
Al —— Ob} 2 ee Normal 
Al ——B) 00)3 pee 
—— pe) op [0b - Calculate 
Al - Check lim. Events 
Attributes 
LoLimit 
HiLimit 
Output Value Command 
; STATUS Operations 
Arrow shape: An operation - Change limit 
uses the in- - Order Events 
> formation Events - Acknowledge 
F HiLimit 
> An operation LoLimit 
updates or AnyLimit 


creates an output 


Figure F-1. Average Calculation 
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F.2.2 OTDL File - averageObj.def 


The first step is to write the OTDL file. The text file below shows the resulting OTDL file:. The 
comments are in ordinary font and the OTDL in courier. 


The object type uses default inheritance. The attributes NAME, DESCRIPTION and STATUS 
are inherited. The instances are configured by the Object Configuration tool. (/tool(coct) 
averageObj /descr(”Average calculation”) /tool (coct) 


Defines status bits. One each for the alarm limits. One to keep track of the acknowledge state. 
/typeDef 
TdStatus: Bitset32 ( 
loLimError: Bit(8); 
hiLimError: Bit (9); 
unAcknowledged: Bit(13);); 
endTypeDef 


Defines the output attribute value, the configurable alarm limit attributes and the limit treatment 
pointer attribute Defines the output attribute value, and the configurable alarm limit attributes 
/part(avrgAttribute) /descr(”Average attr’s and conn’s”) 
loLim: Float [8,2] /configure; 
hiLim: Float [8,2] /configure; 
value: Float [8,2]; 
LimTR: IntShort /input/default (4) /configure/range (1:15); 


Defines the input connections. They are of the object type ai and with a subscription list that 
provides the essential attributes value and status 

Obj1: connect AI (ain_abl_dcx) /input; 

Obj2: connect AI (ain_abl_dcx) /input; 

Obj3: connect AI (ain_abl_dcx) /input; 

optObj: connect AI (ain_abl_dcx) /input/optional; 


endPart 
Defines a subscription to ease other objects subscribing on the object 
/subscription 
avrgCyclic: (value, status); 
endSubscription/ 


Defines the commands changeLimit, order and acknowledge. The two latter commands are for 
objects with event and alarm handling. 
/command 
changeLimit: (IntLong /input limitLoHi, 
Float [8,2]/input newLimit); 
dummyCommand: () ; 
ORDER: (IntSmall /input opCode, IntShort /input opProp, 
IntSmall /input typeOfReq, Boolean /input eventlLog, 
IntLong /input dialogId, Float [8,2] /input aValue, 
IntLong /input dvalue, IntSmall /output status, 
IntShort /output textIndex); 
ACKNOWLEDGE: (IntSmall /input opCode, 
IntShort /input opProp, 
IntSmall /input typeOfReq, Boolean /input eventlLog, 
IntLong /bidirect Id, Float [8,2] /input aValue, 
IntLong /input dValue, IntSmall /output status, 
IntShort /output textIndex) ; 
endCommand 
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Defines events for high and low and any alarm limit transgression, for other object types to 
trigger upon. 
/event 
/* sendEvent inherited from BasicObject */ 
eventHiLim(); 
eventLoLim(); 
eventAnyLim(); 
endEvent 
end 


F.2.3 Normal Operation File - avrgObjNormop.c 


The average object type has one Normal Operation. It calculates the average of the input 

connections and stores the result in an attribute. After the calculation, a limit check is done with 

corresponding alarm handling. Events are raised when alarm limits are transgressed or when 

returning to normal state again. Details on the programming syntax are given in Section 3.7.7, 

Programming the Operations. 

/* The first time the Normal Operation is accessed, it */ 

/* initializes the event handling. */ 

switch (reasonForActivation) { 

case coFirstActivation: 
sendEventData.useSystemTime = gcTrue; 
sendEventData.objectEngUnit[0] =0; 
sendEventData.processSection = 0; 
sendEventData.valueType = DCX_REALV; 
sendEventData.errTreatReference = LimTr; 
sendEventData.errTreatReference = 0; 
sendEventData.blockConditions [TdAlarmBlock]= gcFalse; 
sendEventData.blockConditions [TdPrintBlock]= gcFalse; 
sendEventData.blockConditions [TdRepFailBlock]=gcFalse; 
break; 
default:; 

} 

// Calculate the average. Handle the optional connection 

correctly 


value = Obj1.VALUE + (0bj2.VALUE + Obj3.VALU 
if (optObj == NULL) value = value / 3; 
else value = (value +optObj->VALUE) / 4; 


Gl 


i 


/* Check for alarm limit transgressions or for returning from */ 
/* such transgressions. */ 
/* Generates events when going into or leaving alarm state. */ 


if (value<loLim) 
if STATUS[loLimError] !=(gcBoolean) true { 
STATUS [loLimError] =(gcBoolean) true; /*generate event on*/ 
sendEventData.valueFloat = value; 
sendEventData.eventReason = DCX_ALARM_ON; 
sendEventData.eventAttribute = DCX_ALARM_LO1; 
sendEvent(); /* raise events */ 
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eventLoLim (); 
eventAnyLim (); 
} 
} 
else if (STATUS[loLimError] ==(gcBoolean) true) { 
STATUS [loLimError] =(gcBoolean) false; /*generate alarm off*/ 


sendEventData.valueFloat = value; 
sendEventData.eventReason = DCX_ALARM_OFF; 
sendEvent (); 
} 
if (value>hiLim) { 
if (STATUS[hiLimError] !=(gcBoolean) true) { 
STATUS [hiLimError] =(gcBoolean) true; /*generate alarm on*/ 
sendEventData.valueFloat = value; 
sendEventData.eventReason = DCX_ALARM_ON; 
sendEvent (); 


eventHiLim (); 
eventAnyLim (); 
} 
} 
else if (STATUS[hiLimError] ==(gcBoolean) true) { 
STATUS [hiLimError] =(gcBoolean) false; /*generate alarm off*/ 


sendEventData.valueFloat = value; 
sendEventData.eventReason = DCX_ALARM_OFF; 
sendEvent (); 


} 
returnOmfCode = omfCAP_SUCCESS; 


returnOmfFlag 0; 


The other commands are identical with the corresponding commands of the average object type. 
See the tutorial in Section 3.4.1, Average Example. 


F.3 Outputsender Example 


F.3.1 General 


The outputsender example shows an object type which updates one instance of all Basic Object 
types at each execution of it’s Normal Operation. The example is provided to show how Basic 
Objects are updated. 


The outputsender object type has no other commands and has no events. 


For more information on how to access Basic Objects refer to the Advalnform Object Type 
Reference Manual. 
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F.3.2 ObjectParser and ObjectBuilder Dialog 


F-6 


Check the OTDL file. When OK, add OTDL to the Object Builder, assign the library decodes 
and compile the operation. 


$ ObjectParser -type outputsender.def -mode=parse 
$ ObjectBuilder 


OBJECT BUILDER x.y-z> ty 


TYPE DEFINITION> add outputsender.def 


objectTypeName: outputsender 


TYPE DEFINITION: outputsender> c 


ObjectPrecomp version x.y~-z. 
No syntax failure. 
File generation completed. 


Object Type database updated. 


TYPE DEFINITION: outputsender> exit 


OBJECT BUILDER x.y-z> oper 


OP 


fl 


RATION DESIGN> select outputsender 


OPERATION DESIGN:outputsender> norm 


E 


NORMAL DESIGN:outputsender> add outsend.c 1 “nl” 
NORMAL DESIGN:outputsender> c 1 


NORMAL DESIGN:outputsender> exit 


OPERATION DI! 


E 
E 


SIGN: outputsender> exit 


OBJECT BUILDER x.y-z> quit 


Examples on how to build object handlers are given in the tutorial in Section 3.4.3, 
ObjectBuilder and ObjectParser. 
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F.3.3 Outputsender OTDL file - outputsender.def 


// Object: outputsender.def 

// 

outputsender /descr (“Output to Basic Objects”) /tool (coct) 

if 

// Define Connections 

// 

/part (CompulsoryConns) /descr(“AIs and DIs are compulsory”) 
AlIOlcomp:connect AI /output; 
DIOlcomp:connect DI /output; 

endPart 


/part (OptionalConns) /descr(“Other types are optional”) 
AOOlopt:connect AO /output /optional; 
DOOlopt:connect DO /output /optional; 

TEXTOlopt:connect TEXT /output /optional; 
DATOlopt:connect DAT /output /optional; 

endPart 

end 
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gcBoolean eventLog; 
IntLong dialogId; 
Float aValue; 
gcBoolean toggle; 
IntLong dValue; 


IntSmall status1; 
IntShort textIndex1; 
IntShort delta; 
IntSmall direction; 
IntShort limit; 


IntLong ilValue; 
IntShort iValue; 
IntSmall ibValue; 
gcBoolean bValue; 
gcString tValue; 


switch (reasonForActivation) { 
case coFirstActivation: 


// first time: Initialize parameters to be used 


aValue = 0; 
delta = 10; 
direction = 1; 


limit = 50; 
toggle = gcTrue; 


dvalue = 0; 

ilValue = (int) aValue; 
iValue = (int) aValue; 
ibValue = (int) aValue; 
bValue = toggle; 
tValue = “ “; 

eventLog = gcFalse; 
dialogId = 0; 


statusl = 0; 
textIndexl = 0; 
break; 

default: 


// Bach time: Create real and integer values toggling between 50 


and -50 
// and boolean values that toggl 


between tru 


aValue = aValue + delta*direction; 
ilValue = (int) aValue; 
iValue = (int) aValue; 


and false 
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ibValue = (int) aValue; 

if (direction* (aValue-direction* (limit-delta)) >= 0) 
direction=(-1) *direction; 

toggle = (toggle == gcTrue) ? gcFalse:gcTrue; 
bValue = toggle; 

break; 


if (AOOlopt) 

{ 

AOO0Olopt-—>ORDER (dcVALUE_CHANGE_DCX, dcOUTPUT_DCX, dcPROG, 
eventLog, dialogId, aValue,0, 
statusl,textIndex1); 

} 


r, 
T, 


if (DOOlopt) 

{ 

DOO1lopt-—>ORDER (dcVALUE_CHANGE_DCX, dcACT_VALUE_DCX, dcPROG, 
eventLog, dialogId, aValue,toggle, 
statusl,textIndex1); 

} 


r 


if (DATOlopt) 

{ 

DATOlopt-—>DAT_ORDER (dcVALUE_CHANGE_DCX, dcDAT_INT_WORD, dcPROG, 
eventLog, dialogId, dcINTW_DCX, aValue, 
ilValue, iValue, ibValue,bValue, 
statusl,textIndex1); 


if (TEXTOlopt) 
{ 
TEXTOlopt—>TEXT_ORDER (dcVALUE_CHANGE_DCX, dcTD_INTL_DCX, 
dcPROG, eventLog, dialogId, dcINTW_DCX, 
aValue, dValue, bValue,tValue, 
statusl1,textIndex1); 


AIOlcomp.ORDER (dcVALUE_CHANGE_DCX, dcACT_VALUE_DCX, 
dcPROG, eventLog, dialogId, aValue, dValue, 
statusl,textIndex1); 


E 


Tr 


DIO1lcomp.ORDER (dcVALUE_CHANGE_DCX, dcACT_VALUE_DCX, 
dcPROG, eventLog, dialogId, aValue,toggle, 
statusl,textIndex1); 
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F.4 Outputfcm Example (MOD 300) 


F.4.1 General 


The outputfem example shows an object type which updates some FCM object types at each 
execution of it’s Normal Operation. The example is provided to show how FCM objects are 
updated. You can find the example, together with the average example, in the directory: 
/opt/advant/ObjectBuilder/examples/ 


In the same directory, there is a script which allows you to enter the object types to the 
ObjectBuilder and build a run time environment to execute them. 


outputfcm has no other commands and has no events. 
The object type has help attributes: 
° Two attributes that show the latest and the next execution time. 


° Three attributes which make it possible to configure the algorithm of the output value as 
well as to inspect the current output from an instance. 


NOTE 


The outputfcm object type has an FCM output connection. The FCM type is 
abstract, that is can’t be instantiated. However, it is inherited by all other FCM 
object types. This means that any FCM object type can be configured towards this 
connection. The FCM commands PUT_RESULT and PUT_OUT_MODE 
commands are used to update the connections. They are valid for all FCM object 


types. 


F.4.2 ObjectParser and ObjectBuilder dialog 
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Check the OTDL file with the ObjectParser. When OK, add OTDL to the Object Builder, assign 
the library decodes and compile the operation. 


$ ObjectParser -type outputfcm.def -mode=parse 


ObjectParser version 1.0-0 
ObjectPrecomp version 1.0-0 
No syntax failure 
Object Type database not updated 
No files generated 


$ ObjectBuilder 


OBJECT BUILDER B1> ty 


TYPE DEFINITION> add outputfcm.def 


objectTypeName: outputfcm 


TYPE DEFINITION: outputfcm> c 


ObjectPrecomp version Bl. 


No syntax failure. 
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File generation completed. 


CO database updated. 


TYPE DEFINITION: outputfcm> exit 


OBJECT BUILDER B1> oper 


OPERATION DESIGN> select outputfcm 


E 


OP 


ea 


RATION DESIGN:outputfcm> norm 


NORMAL DESIGN:outputfcm> add outputfcm.normop 1 “n1” 


NORMAL DESIGN:outputfcm> c 1 
cc: “../text/cotype.hh”, line 263: warning: - 
cc: “../text/cotype.hh”, line 278: warning: - 


NORMAL DESIGN:outputfcm> exit 


OPERATION D 


E 
E 


SIGN:outputfcm> exit 


OBJECT BUILDER Bl1> quit 


Examples on how to build object handlers are given in the tutorial in Section 3.4.3, 
ObjectBuilder and ObjectParser. 


F.4.3 outputfcm OTDL file - outputfcm.def 


// FILE :outputfcm.def 

// 

outputfem /descr (“IMS MOD 300 FCM Output Example”) /tool (coct) 
// 


/part (ScheduleTimes) /descr(“Schedule times”) 
NextScheduleTime: String[30] /configure; 
LastScheduleTime: String[30] /configure; 
FloatValue: Float[10,4] /default (0.0) /configure/range (- 
90:2 0:250..0:) 7 
DigitalValue: Float[10,4]/default (0.0) /configure/ 
range (0.0:1.0); 
DeltaValue: Float[10,4]/default (1.0) /configure/ 
range (0.0:25.0); 

endPart 


/* Define Connections */ 

/part (AOUT_Connections) /descr (“AOUT_FCM”) 
AOUT_FCMlopt:connect AOUT_FCM /output /optional; 
AOUT_FCM2Zo0pt:connect AOUT_FCM /output /optional; 
AOUT_FCM30pt:connect AOUT_FCM /output /optional; 
AOUT_FCM4opt:connect AOUT_FCM /output /optional; 
AOUT_FCM5o0pt:connect AOUT_FCM /output /optional; 

/endPart 


3BSE 001 012R0501 F-11 


AdvaBuild® Object Type Builder User’s Guide 
Appendix F Object Type Examples 


/part (DOUT_Connections) /descr (“DOUT_FCM”) 
DOUT_FCMlopt:connect DOUT_FCM /output /optional 
DOUT_FCM2Zopt:connect DOUT_FCM /output /optional 
DOUT_FCM30pt:connect DOUT_FCM /output /optional 
DOUT_FCM4opt:connect DOUT_FCM /output /optional 
DOUT_FCM5opt:connect DOUT_FCM /output /optional 

/endPart 


Ne Ne Ne 


~e 


~ 


/part (DATA_FCM_Connections) /descr (“DATA_FCM”) 
DATA_FCMlopt: connect DATA_FCM /output /optional; 
DATA_FCM2opt: connect DATA_FCM /output /optional; 
DATA_FCM30pt: connect DATA_FCM /output /optional; 
DATA_FCM4opt: connect DATA_FCM /output /optional; 
DATA_FCM5opt: connect DATA_FCM /output /optional; 

/endPart 


/part (FCM_Connections) /descr (“FCM”) 
FCMlopt: connect FCM /output /optional 
FCM2opt: connect FCM /output /optional 
FCM30pt: connect FCM /output /optional 
FCM4opt: connect FCM /output /optional 
FCM5o0pt: connect FCM /output /optional 

/endPart 

end 


Ne Ne Ne 


~ 


~ 


F.4.4 outputfcm Normal Operation - outputfemNormop.c 


static IntSmall dataType; 
static Float aValue; 
static gcBoolean toggle; 

static Float dValue; 
static Float delta; 
static IntSmall direction; 
static IntShort limit; 
static gcBooleantrace_on; 


For each execution, the new values of the current and the next execution are saved into the 
corresponding attributes. 

NextScheduleTime = nextExecution; 

LastScheduleTime = previousExecution; 


The first time the object executes, it sets all FCM’s connected as outputs to Manual mode. if not, 
the output will be ignored by the object. 


switch (reasonForActivation) 
{ 
case coFirstActivation: 
aValue = FloatValue; 
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delta = DeltaValue; 
dValue = DigitalValue; 
direction = 1; 

limit = 50; 

toggle = gcTrue; 


if (AOUT_FCMlopt) 
{ 
AOUT_FCMlopt-—>PUT_OUT_MODE (0); 


if (AOUT_FCM2opt) 


AOUT_FCM2o0pt—>PUT_OUT_MODE (0) ; 
} 


Etc. for each connected FCM output. 


if (FCM5opt) 
{ 
FCM5o0pt—>PUT_OUT_MODE (0) ; 
} 
break; 
default: 


For each execution a new Float and a New Digital value is calculated. 


aValue = aValue + delta*direction; 
if (direction* (aValue-direction* (limit-delta)) >= 0) 
direction=(-1) *direction; 
toggle = (toggle == gcTrue) ? gcFalse:gcTrue; 
if (toggle) 
dValue=0.0; 
else 
dValue=1.0; 
FloatValue = aValue; 
DigitalValue= dValue; 
break; 


For each configured connection, set a new result corresponding to Digital Value or FloatValue. 


if (AOUT_FCMlopt) 
{ 
AOUT_FCMlopt-—>PUT_RESULT (aValue) ; 


if (AOUT_FCM2Zopt) 
{ 
AOUT_FCM2o0pt-—>PUT_RESULT (aValue) ; 
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} 
Etc. for each AOUT_FCM. 


if (DOUT_FCMlopt) 
{ 


DOUT_FCMlopt->PUT_RESULT (dValue) ; 


if (DOUT_FCM2Zopt) 


DOUT_FCM2opt-—>PUT_RESULT (dValue) ; 


Etc. for each DOUT_FCM. 


if (DATA_FCMlopt) 
{ 


Etc. for each DATA_FCM. 


if (FCMlopt) 
{ 
FCMlopt-—>PUT_RESULT (aValue) ; 


if (FCM2opt) 


FCM2o0pt—>PUT_RESULT (aValue) ; 


Etc. for each FCM. 


DATA_FCMlopt-—>PUT_DATAI1 (aValuetl 
DATA_FCMlopt-—>PUT_DATA2 (aValuet2 
DATA_FCMlopt-—>PUT_DATA3 (aValue+3 
DATA_FCMlopt—>PUT_DATA4 (aValuet+4 
DATA_FCMlopt-—>PUT_DATA5 (aValuet5 
DATA_FCMlopt-—>PUT_DATA7 (aValuet7 
DATA_FCMlopt-—>PUT_DATA8 (aValue+8 
DATA_FCMlopt-—>PUT_DATA9 (aValue+9 
DATA_FCMlopt—>PUT_DATA10 (aValue+10) ; 
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F.5 Example readHistoryObject. 


F.5.1 Description 


This example shows how to read history data using library functions based on the User API 
facilities. The functions can be called from User Objects. The idea of this example is that it will 
read the value from a history log from a specific time. 


F.5.2 How to use 


F.5.3 Functionality 


Use the ready made scripts to build the readHistoryObject as user ocsmgr. 


Run the script which builds the object type: 
/opt/advant/ObjectBuilder/examples/userapi_examples/readHistoryObject_build. 


Run the script which builds the object handler: 
/opt/advant/ObjectBuilder/examples/userapi_examples/readHistoryObjectHandler_build. 


Because the readHistory is a new object type, you must run a tdgen as described in Section 
3.7.4, Updating Object Type Directory. 


The functionality of the readHistoryObject is as follows: 


The object type reads the value of a History numeric log from a specific time. The received 
values are not stored or used in this example, they are only printed in the stdout log 
file(dcSystem.log or codaemon.log). When the normal operation is finished the data will 
be lost. 


It consists of one input connection and one library routine. The input connection is a DI 
event trigger input and the normal operation of the User Object will only be executed on a 
positive flank i.e. when the value of the DI goes from zero to one. 


The User API routines consists of one routine called readHistory. 
The routine requires the name of the History log and the time from which the data shall be 
retrieved. 


Errors that occur in the object originate first of all from the routines based on User API i.e. 
if you submit a log name that do not exists. Because the log names are transferred through 
attributes, check if the log names are valid is not possible until the routines have been 
executed. 


Algorithm (Normal Operation) 


Each time the operation is executed it reads the value from the specified History log. The 
normal operation can be executed either by a trig from the DI input or a scheduled 
execution, or both. 


Input 
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DI_TRIGGER: Input connection of the DI trigger. 
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Output 
none 

Attribute 
logName: The name of the History log that the values shall be read from. 
statusString: Status from execution of normal operation. 


fromDate: The date from which the data shall be retrieved with the syntax yymmd4d, ex. 
970730. 


fromTime: The time from which the data shall be retrieved with the syntax hhmmss, ex. 
143035. 


User API library routines 
readHistory: Reads the data from the History log. 
Events 


none 


F.6 Example readMULTIDATObject (Master specific) 


F.6.1 Description 


This User Object example shows how to read a MultiDat object without an external User API 
application.Instead this example will use library functions based on the User API facilities. The 
functions can be called from User Objects. The idea of this example is that it will read the 
values from a MultiDat object. 


F.6.2 How to use 
Use the ready made scripts to build the rea4(MULTIDATObject as user ocsmgr. 


1. Run the script which builds the object type: 
/opt/advant/ObjectBuilder/examples/userapi_examples/readMULTIDATObject_build. 


2. Run the script which builds the object handler: 
/opt/advant/ObjectBuilder/examples/userapi_examples/readMULTIDATObjectHandler_b 
uild. 


3. Because the reaAMULTIDATObject is a new object type, you must run a tdgen as 
described in Section 3.7.4, Updating Object Type Directory. 


F.6.3 Functionality 
The functionality of the readMULTIDATObject is as follows: 


° The object type read the values from a MultiDat object. The number of consecutive DAT 
objects to be read is set by an attribute, nrOfDAT. The received values are not stored or 
used in this example, they are only printed in the stdout log file(dcSystem.log or 
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codaemon.log). When the normal operation is finished the data will be lost. 


° It consists of one input connection and one library routine. The input connection is a DI 
event trigger input and the normal operation of the User Object will only be executed on a 
positive flank i.e. when the value of the DI goes from zero to one. 


° The User API routines consists of one routine called readMULTIDAT. 


° The routine requires the name of the MultiDat object and the number of consecutive DAT 
objects to read. 


° Errors that occur in the object originate first of all from the routines based on User API i.e. 
if you submit a MultiDat object name that does not exists. Because the object names are 
transferred through attributes, the check if the object names are valid is not possible to do 
until the routines have been executed. 


Algorithm (Normal Operation) 


Each time the operation is executed it reads the value from the specified MultiDat 
object.The normal operation can be executed either by a trig from the DI input or a 
scheduled execution, or both. 


Input 
DI_TRIGGER: Input connection of the DI trigger. 
Output 
none 
Attribute 
objectName: The name of the MultiDat object. 
statusString: Status from execution of normal operation. 
nrOfDAT: Number of consecutive DAT objects to read. 
User API library routines 


readMULTIDAT: Reads the values from the consecutive DAT objects using the MultiDat 
object interface. 


Events 


none 


F.7 Example writeObject. 


F.7.1 Description 
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This User Object example shows how to achieve a generic write function without an external 
User API application. Instead this example will use library functions based on the User API 
facilities. The functions can be called from User Objects. The idea of this example is that it will 
be able to write a float value to an object of any of the types AI, AO, DI, DO, DAT or TEXT. It 
is easy to extend the example to support for example most MOD 300 object types. 
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F.7.2 How to use 


Use the ready made scripts to build the writeObject as user ocsmgr. 


1. 


F.7.3 Functionality 


Run the script which builds the object type: 
/opt/advant/ObjectBuilder/examples/userapi_examples/writeObject_build. 


Run the script which builds the object handler: 
/opt/advant/ObjectBuilder/examples/userapi_examples/writeObjectHandler_build. 


Because the writeObject is a new object type, you must run a tdgen as described in Section 
3.7.4, Updating Object Type Directory. 


The functionality of the writeObject is as follows: 


The object type writes a float value to an object. The object to send to and the value is 
stored in attributes in each instance. 


It consists of one input connection and one library routine. The input connection is a DI 
event trigger input and the normal operation of the User Object will only be executed on a 
positive flank i.e. when the value of the DI goes from zero to one. 


The User API routines consists of one routine called writeFloat. This routine is 
implemented to send a value to the following types: AI, AO, DI, DO, DAT, TEXT. The 
routine can easily be extended to be able to send values to other object types. For MOD 
300 this is very simple. For almost all attributes there is a corresponding operation called 
PUT_” AttributeName” which has one parameter, the new value. So, if an attribute exists 
in the type directory the corresponding operation name can easily be created and verified. 


The routine requires the name of the object and the float value. 


Errors that occur in the object originate first of all from the routines based on User API i.e. 
if you submit a object name that do not exist. Because the object names are transferred 
through attributes, check if the object names are valid is not possible until the routines 
have been executed. 


Algorithm (Normal Operation) 


Input 


Each time the operation is executed it writes the value to the specified object. The normal 
operation can be executed either by a trig from the DI input or a configured execution, or 
both. 


DI_TRIGGER: Input connection of the DI trigger. 


Output 


none 


Attribute 
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objectName: The name of the object that the values shall be send to. Must be of the 
following types: AI, AO, DI, DO, DAT, TEXT. 


objectCallStatus: Status from execution of normal operation. 
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value: The float value which is sent to the object. 
User API library routines 

writeFloat: Writes the value to the specified object. 
Events 


none 
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Appendix G External Communication Library 


G.1 General 


G.1.1 Introduction 
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In many IMS deliveries there are PLCs, DCS systems, or other external systems (called EC) that 
cannot be connected to the ABB automation system via Advant Controllers. Example reasons 
include: 


° The EC communicates through IEE802.3 carriers. No such facility currently exists on our 
Gateway solutions. 


° There are no Advant Controllers at the site. 


° Another vendors IMS or Lab computer needs to be connected. They are not suitable to 
connect through an Advant Controller. 


The most important requirement is to access external data from Advant clients (AdvaInform 
History, AdvaInform Reports, Event and Alarm treatment, Operator Station Displays, User 
Objects, Calculations) and to read and send information to the External Computer. 


The User Object options AdvaBuild Object Type Builder and AdvaInform Object Handling 
provide a solution to these requirements according to Figure G-1. 


Va 


- 


Clients objects OO oO 
- History lg euler o 
- OS Displays D 
-A&E System 


- Other User Objects 
- Calculations etc. 


User Object 
solution 


Read and Write of 
Object Information 


NM 


Figure G-1. Principal solution to External Communication requirement 


wy, 


The EC systems have object types corresponding to ABB’s AI, AO, DI and DO objects. Other 

frequently occurring object types include Counter objects, Status objects, and Laboratory value. 
They are simple object types with only a few attributes. All these object types either exist within 
IMS if AdvaInform Object Handling is installed or they can be built using the ObjectBuilder. 
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The principles for the solution are: 


1. 
2. 


Communication with the EC is achieved through software purchased by the EC’s supplier. 


All data points are represented as User Objects in the IMS, making them fully integrated 
into the ABB Advant world. User Object Types can be implemented by using AdvaBuild 
Object Type Builder. 


Use AdvalInform Object Handling configuration tools to create and configure instances of 
the object types. These instances will correspond to instances in the External Computer. 


The External Communication library is used to update object instances with information 
from the EC source. The EC library provides higher performance than using the User API 
library as you buffer a number of object updates in one request. 


If output to the EC is required, program that support into the User Objects. When a 
command is sent to the User Object, the command sends a message to the Application 
handling the EC communication. It can then convert the message to a suitable format and 
forward it to the EC. 


The detailed solution is described in Figure G-2. 


Advant functions, applications 


Clients 
- History | 
- OS Displays 
-A&E System 

- Other User Objects 
- Calculations etc. 


Unpack 
and call 


ObjectHandler 


EC-library E.g: pipe 
Application Program 


IMS Communication software 


IEE802.3 or 
Serial Port 


External on oe on 


Computer LC eK ~~ Data 
O oO points 
Or Ov 0 (objects) 


Figure G-2. Details of the EC solution 
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G.1.2 The EC Library 


The EC library uses a buffer to achieve high performance. A number of commands are stored in 
a buffer and sent in one request to the objects execution environment (the object handler). 


The EC library consists of three routines—bceiInit, bceiExecOperation, and bceiSend. 
The bceiExecOperation is called from all implementations of object type specific commands. 
The relation between the routines is described in the figure below: 


beeilnit p> Initialize buffer 


Your own 3 
Object Type +> bceiExecOperation ————_> Fill the buffer 
specific routines 


bceiSend: p> Send buffer 


Figure G-3. The relation between the routines bceilnit, bceiExecOperation, and bceiSend 


To send a number of commands to objects, handled by one object handler, execute the following 
(in pseudo code): 
bceilInit; 
while not eofDataToSend { 
unpack data into command parameters 
switch objectType 
case objectTypex: 
switch (bceiObjTypeCommandxX (parl1,par2,par3) ) { 
case bciSUCCESS; 
break; 
case bciNOT_FOUND: 
“error treatment, object name not found locally” 
break; 
case bciNO_SPACE: 
Error treatment, buffer full. Either send current 
buffer and then execute the bceiObjTypeCommandx 
again or terminate with error message 
break; 


}; 
break; 


case objectTypeY 


break; 
}; 
}; // end while 
bceiSend (objectHandlerName) ; 


The bceiObjectTypeCommandxX is a routine that you create for the object type command X. 
It unpacks parameters and gives the right information in the call to the bceiExecOperation 
function. A number of existing, ready-made bceiObjecTypeCommand implementations are 
provided as examples. See Section G.2 and the source files under 
/products/data/standard/UserObjects/examples/. 


If you want to send information to more object handlers, the whole cycle needs to be repeated. 
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G.1.3 Required Software 


To implement applications with the EC library, you must purchase the IMS C development 
option or you can use the C++ compiler provided as part of Object Type Builder. If updating 
Basic Objects is not enough and other object types are required, you need to use the AdvaBuild 
Object Type Builder to build the required Object Types. 


G.2 Programming an Object Type Specific Command 


G.2.1 Basic Objects 


You begin by programming your User Object types with Object Type Builder or by making sure 
that the object types you are going to use are installed in the type directory. Then you can start 
programming the object type specific commands that use the External Communication library. 


Before you program any object type specific command, look at the corresponding commands 
provided for the IMS Basic Objects. The include file beeiCommands.h and the implementation 
file beeiCommands.c are provided as examples. The implementation of the command to the AI 
object is described below. 


G.2.2 The bceiExecAlOrder Routine. 


G.2.2.1 Steps to Perform 


The implementation of a command to an object type can be split into the following steps: 
1. Make the appropriate include file. 
2. Declare the call to the library function 


3. Implement the library function 


G.2.2.2 The Include File 


Make a define statement according to normal C programming practice. 


#ifndef bceiCommands_h 
#define bceiCommands_h 
#ifdef cplusplus 
extern “C” { 

#endif 
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G.2.2.3 Declare the Call to the Library Function 


Make it a ruel to describe the parameters and the functionality of the function. 


BciStatus bceil 


ExecATOrder ( 


const char* objectName, 
float value); 


/* 


PARAMETERS 


objec 


value 
DESCRIPTION 


The bceil 


opProper 


tname = Nam 


of object instance 


= Value to be set for the object 


Manual. 


af 


G.2.2.4 Implement the Library Function 


ExecAlOrder is the specialized function for setting 
the value of an AI object. It uses the appropriate opCode and 
ty to do that according to the Object Type reference 


The implementation requires that you include a number of standard C and IMS include files: 


#incl 
#incl 
#incl 
#incl 
#incl 
#incl 
#incl 
#incl 
#incl 
#incl 
#incl 


lude 
lude 
lude 
lude 
lude 
lude 
lude 
lude 
lude 
lude 
lude 


<stddef. 
<stdlib. 
<string. 


<sys/types.h> 


<time.h> 


<mall 


loc. 
<omfType 
<omf_AI. 


h> 
Directory.h> 


n> 


<dccodes.hh> 
<bciUserAPI.h> 
<bceiCommands.h> 


The implementation of the code uses the C structures and the C constants that are defined in the 
Type Directory when an object type is included there. Se the Object Type Reference manual for 
more information. The information is included as the omf£_ATI .h include file is included. 
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A construct is available for storage of all parameters: 
BciStatus bceil 


{ 
f* BL */ 


ExecATOrder ( 


BciStatus aiResult; 
BciObjStatus aiObjStatus; 
int aiOperation 


const char* objectName, 


float value) 


= { OMF_AIORDERID }; Loree = from omf_AIl. 
size_t aiOperSize = { sizeof( Omf_AIORDER ) };<-from omf_AI. 


Omf_ATORDER aiOperOrder; <------ from omf_AI.h 
aiOperOrder.opCode = dcVALUE_CHANGE_DCX; <--- from dccodes.hh 
aiOperOrder.opProp = dcACT_VALUE_DCX; <--- from dccodes.hh 
aiOperOrder.typeOfReq = dcPROG; <--- from dccodes.hh 
aiOperOrder.eventLog = gcFalse; According to the 
aiOperOrder.dialogId = 0; Object Type Reference 
aiOperOrder.aValue = value; Manual 
aiOperOrder.dValue = 0; 
aiOperOrder.status = 0; 
aiOperOrder.textIndex = 0; 
aiResult = bceiExecOperation( (char*) objectName, 
aiOperation, 
aiOperSize, 


return (aiResult); 


} 


&aiOperOrder) ; 
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G.3 Creating your External Communication Program 


G.3.1 Includes 


You need the following includes in your test program assuming that the object type specific 
commands are declared in the include file bceiCommands.h: 


#include <stddef.h> 

#include <string.h> 

#include <malloc.h> 

#include <omfTypeDirectory.h> 
#include <omfAttributeT.h> 
#include <bciUserAPI.h> 
#include <bceiCommands.h> 


G.3.2 Example: The C program Updating Basic Objects 
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A description of setting the value of the Basic Object AI follows: 


1. 


Make the appropriate includes as described above and then declare your main program. 
int main( int argc, char* argv[] ) 


As the next step, declare the required local variables and initialize any C++ constructors 
{ 
/* AI */ 
BciStatus aiResult; 
char* aiObjNames [MAX_NO_OF_OBJS]; 
float aiFloat; 


#ifdef __hpux 

/* 

// If HP environment: run constructor for C++ as program coded 
inc 

Ky: 

—main(); 

#endif 


Initialize the buffer: 
bceilInit(); 
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4. Send an AI value. In a real application this is repeated for all the received AI values. 
Error treatment should be done in the level above the library routine, see Section G.1.2 . 
The print-outs are just for documentation purposes and should not exist in a final version: 
PROBL *Y 
aiFloat = 1.234; 
aiResult = bceiExecAIOrder( (char*) aiObjNames[0], aiFloat ); 
if (aiResult != bciSUCCESS) 
printf( “%s: bciExecOperation(%s) ERROR %Sd\n”, 
argv[0], aiObjNames[0], aiResult ); 


else 
printf( “Ss: AI Object named ’%s’ successfully updated\n”, 
argv[0], aiObjNames[0] ); 


5. When all commands are given, execute them all in one request: 
strcpy (objectHandlerName, “basichandler”) ; 
bceiSend( (char*) objectHandlerName) ; 


6. Terminate the program: 
exit( 0 ); 


G.4 Initialize External Interface Buffer 
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This function is designed to initialize the external communication functions. The initialization 
prepares the buffer and initializes for all calls to other EC routines that follow. 


Calling format 


Name: bceilnit 


Synopsis 


BciStatus bceiInit() 


Parameters 


None 


Description 


The external communication functions maintain an internal request buffer where all requests 
submitted through one of the functions are put. The function bceiInit flushes and initializes this 
request buffer so that the next bceiExec. request will be the first operation request in the buffer. 


Return Value 


bceiInit = none (A simple initialization which can’t go wrong) 
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G.5 Execute Operation 


Introduction 


The execute operation stores one command request into the external communication buffer. 


Calling format 


Name: bceiExecOperation 


Synopsis 


BciStatus bceiExecOperation( 
const char*objectName, 
int operationId, 
int argSize, 
void* arguments) 


Parameters 


objectName = Name of object instance for operation request 
operationId = Operation id. 
argSize = Number of bytes of argument data in Argument 
arguments= Pointer to array or structure or other data type 
where all arguments are stored, one after the other, in the order 
the arguments are defined for the operation. 


Description 


The bceiExecOperation function is the generic function used to put one execution request for 
one operation in the EC request buffer. To make sure the buffer is empty, bceiInit must be called 
before the first bceiExecOperation call. Subsequent calls to bceiExecOperation put all requests 
in the same request buffer one after the other. No requests are sent to the object system unless 
bceiSend is called. 


The bceiExecOperation function resolves the given object name. The majority of the possible 
error messages from the call are related to the object name resolving. 


Return Value 
bceiExecOperation= bciSUCCESS if OK 
= beiILLEGAL_NAME if illegal characters are included in the name 
= bciNOT_FOUND if the object does not exist in the IMS node. 
= bciNO_SPACE if the send buffer is full 


= other error codes: See User API documentation. 
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G.6 Send the Buffer 


Introduction 


The send function sends the buffered commands to the specified object handler. 


Calling Format 


Name: bceiSend 


Synopsis 


BciStatus bceiSend(const char* objectHandlerName); 


Parameters 


objectHandlerName = Name of object handler to send the command (buffer) to. 


Description 


The bceiSend function sends the EC request buffer to the object system. All requests put in the 
request buffer, since the last bceiInit call, are now sent to the object system. After a successful 
bceiSend call, the request buffer has been sent but is not flushed. The request buffer must be 
flushed through a bceilnit call before new requests are put in the buffer. 


Return Value 


bceiSend=  (bciSUCCESS) if OK 
= beiFailure 
If the object handler fails to perform any of the operations. 
Error logs will be created to document the failing objects. Use 
the IMS Error Log Display to view the details. 
= beixx 


See the documentation of the User API in the Advalnform 
User API for documentation of other possible return statuses. 
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G.7 Examples 


G.7.1 The Basic Objects example 


An example of how to use the EC library is provided in the directory 
/products/components/standard/UserA PI/examples/: 


° bceiCommands .h and bceiCommands .c for the basic object command 
implementations. The Makefile: beeiMakefile (execute make -f bceiMakefile) lets 
you compile bceiCommands. 


° bceiLibraryExample.c gives an example of an implementation which makes it 
possible to update basic objects. The Makefile bceiMakefile lets you compile and 
link the test program. To execute it, write: 


bceiLibraryExample AlobjectName AOObjectName DIObjectName 
DOObjectName DATObjectName TextObjectName. 


Only the AI object name is compulsory. 


G.7.2 Other ways to use the EC Library 


The EC library can also be used for other types of applications where data from the applications 
needs to be available for the user’s of the ABB system, for example: 


By storing results of optimizations in local IMS basic objects, the optimization results 
become available for presentation on the Operator Station and available through SQL for 
e.g. spread-sheet programs in connected PC’s. 


G.7.3 Using C or C++ Compilers 


You can compile Your EC library application with the C or with the C++ compiler. The example 
Makefile bceiMakefile is pre-configured for a C compiler. To change to the C++ compiler 
you change the bceiMakefile variable CC to CC using the editor of your preference. 

The default (C compiler) is c89+e. 


G.8 Linking your Application 


To link your application, include the bceiLibrary.a as provided under 
/products/components/ObjectHandling/1ib. Since additional IMS libraries are 
required as well, copy the Make file bceiMakefile and use it as a base for your development. 
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Appendix H Event Handling Constants 


H.1 Event Reasons 


Event reasons, see Table H-1. 


Table H-1. Event Reasons 


Constant name Explanation 
DCX_NORMAL Describes the object as in a normal state 
(again). 
DCX_BLOCKED The object is blocked. The event property 


describes what is blocked. 


DCX_DEBLOCKED The object is deblocked. The event 
property describes what is deblocked. 


DCX_ALARM_ON The event will be acknowledged, i.e., it is 
an alarm. 


DCX_ALARM_OFF The object has left the alarm state. 


DCX_VAL_CHANGE A value change has occurred. The event 
property gives more specific information 
on what has been updated. 


DCX_EVENT_ON An event is raised. The event property 
gives additional information, e.g., alarm 
limit. 


DCX_EVENT_OFF The object leaves the event state. 
The event property gives additional 
information, e.g., alarm limit. 
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H.2 Event Properties 


The following possible event properties exist. This list shows their constant names and values. 


The comments show their meaning. 
DCX_EDUM_EV_PROP = 1; 
DCX_EIND_VALUE = 2; /* value */ 
DCX_EERROR = 3; /* error */ 
DCX_EHI_LIM2 = 4; /* ABOVE hI_LIM2 */ 
DCX_EHI_LIM1 = 5; /* ABOVE hI_LIM1 */ 
DCX_ELO_LIM1 = 6; /* BELOW 10_LIM1 */ 
DCX_ELO_LIM2 = 7; /* BELOW 10_LIM2 */ 
DCX_EACT_VALUE = 8; /* value */ 
DCX_EDIST_PRINT = 9; /* print_blk */ 
DCX_EDIST_ALARM = 10; /* alarm_blk */ 
DCX_EPROC_UPDATE = 11; /* upd_blk */ 
DCX_EDISTURB = 12; /* disturbance */ 
DCX_EOTRAVI = 13; 

DCX_ECTRAVI = 14; 

DCX_EVC_N = 15; 

DCX_EVO_N = 16; 

DCX_ESPAREM = 17; 

DCX_EEMERGM = 18; 

DCX_EPOSF = 19; 

DCX_EPOSINDF = 20; 

DCX_ESWGEF = 21; 

DCX_EPOWF = 22; 

DCX_EALTF = 23; 

DCX_EDCM_ERR = 24; 

DCX_ESERVUC = 25; 

DCX_EPC_BLK = 26; 

DCX_EHW_ERR = 27; 

DCX_EMANUAL = 28; 

DCX_EAUTO = 29; 

DCX_EJUMPERROR = 30; 
DCX_EACKPOSFAULT = 31; 
DCX_EGENNOVERR = 32; 

DCX_EORDER = 33; 

DCX_EINCREASE = 34; 
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DCX_EDECREASE = 35; 
DCX_ESTARTOFF = 36; 
DCX_EPOSALARM = 37; 
DCX_EPOSPRINT = 38; 
DCX_EFAULTALARM = 39; 
DCX_EFAULTPRINT = 40; 
DCX_EPO_N = 41; 
DCX_EP1_N = 42; 
DCX_ESEQAL = 43; 
DCX_ESTEPAL = 44; 
DCX_EPOS = 45; 
DCX_EHOLD = 46; 
DCX_ESTART = 47; 
DCX_ERESET = 48; 
DCX_ESTEP = 49; 
DCX_EUNCOND = 50; 
DCX_EJUMP = 51; 
DCX_EJPOS = 52; 
DCX_ENOOFT = 53; 
DCX_EINTERVT = 54; 
DCX_ERUN =55; 
DCX_EEND = 56; 
DCX_ECOND = 57; 
DCX_EAUTOIND = 58; 
DCX_EMANIND = 59; 
DCX_EHOLDIND = 60; 
DCX_EUNCONDIND = 61; 
DCX_EMVL2 = 62; 
DCX_EMVLI = 63; 
DCX_EMVH I = 64; 
DCX_EMVH2 = 65; 
DCX_EDEVL = 66; 
DCX_EDEVH = 67; 
DCX_ELOCALFL = 68; 
DCX_EMANEL = 69; 
DCX_EAUTOFL = 70; 
DCX_EEIFL = 71; 
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DCX_EE2FL = 72; 
DCX_EE3FL = 73; 
DCX_EAUXERR = 74; 
DCX_EMAXLIM = 75; 
DCX_EMINLIM = 76; 
DCX_EGENBSLOC = 77; 
DCX_EGENBSMAN = 78; 
DCX_EMMCORDER = 79; 
DCX_EAIERR = 80; 
DCX_EAOERR = 81; 
DCX_EE1 = 82; 
DCX_EE2 = 83; 
DCX_EF1ALARM = 84; 
DCX_EF1PRINT = 85; 
DCX_EF2ALARM = 86; 
DCX_EF2PRINT = 87; 
DCX_EF3ALARM = 88; 
DCX_EF3PRINT = 89; 
DCX_EF4ALARM = 90; 
DCX_EF4PRINT = 91; 
DCX_EE3 = 92; 
DCX_ETORQEF = 93; 
DCX_EMANFORCE = 94; 
DCX_ESTOP = 95; 
DCX_ENEXT = 96; 


DCX_ESEQINDPRINT = 97; 
DCX_ESEQINDALARM = 98; 


DCX_EOUTPUT = 99; 


There are more event properties than this in the ABB Master system. They are specific for 
object types of the ABB Master process station objects. Still, if they are needed, you can define 


them locally. 
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Appendix | Debugging of User Object Applications 


1.1 Introduction 


You debug your User Object application using the HP xdb Symbolic Debugger, which is included in 
the Advant Station 500 Series IMS (Basic Unit). To take full advantage of xdb, you should read the xdb 
User’s Manual. This section describes the UserObject specific methods of source code debugging. 


1.2 Instructions 


.3 Example 
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When application source code is added within the ObjectBuilder, it is copied and renamed to an inter- 
nally used directory which must be referred to from within the debugger. The directory for an object type 
is: 
/home/opt/advant/UserObjects/standard/TypeDir/<object type name> 
The source files to debug under that directory have the following names: 
Normal operations: 
<object type name>normal<n>.def (Where <n> is | - 10) 
Command operations: 


<object type name><command name>.def 


The ObjectHandler must be built with debuggable code. Do this by adding the switch -DEBUG to the 
Object Builder BUILD command. 


Start the object handler as usual using Object Handlers or Object Builder (see example below). 
Login as ocsmgr and adopt the object handler using xdb. 


As an example, the ObjectBuilder application example average is prepared and executed in the debug- 
ger. 

$ ObjectBuilder 

OBJECT BUILDER> build 

BUILD: averagehandler> select averagehandler 

BUILD: averagehandler> build -debug 

BUILD: averagehandler> start 

BUILD: averagehandler> exit 

S$ ObjectHandlers list 

NAME Configured_State Actual_State ProcessID 


averagehandler STARTED STARTED 3341 

$ su ocsmgr 

Password: xxxxxx 

S$ ed /home/opt/advant /UserObjects/standard/TypeDir/average 

S$ xdb -P 3371 /opt/advant/ObjectBuilder/handlers/bin/averagehandler 
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IMS Object Type Builder 


: // The first time the Normal Operation is accessed it initializes 
// event handling 


switch (reasonForActivation) { 
case coFirstActivation : 
sendEventData.useSystemTime = gcTrue; 
sendEventData. objectEngUnit [0] = 0; 
sendEventData.processSection = 0; 
sendEventData.valueType DCX_REALV; 
averagenormall.def Procedu unknown 
Shared-library tables will be loaded at that time. 
Stack traces may not be possible until you are stopped in user code. 


1 
2 
3 
4: 
S: 
6: 
vas 
8: 


= 
oo 


>v averagenormall.def 


>b 5 
Overall breakpoints state: ACTIVE 
Added: 
1: count: 1 Active coaverage: :hiddenNormal Implement ation1(const CoActivat 
ionReason, const char *): 5: switch (reasonForActivation) 
ce 


if i 


Figure I-1. Setting break point in a normal operation 


IMS Object Type Builder 


switch (limitLoHi) { 
case 1: 
if (newLimit<hiLim) 


loLim=newLimit ; 
normalOperation(); 
break; 


+ 


case 2: 
if (newLimit>1loLim) 


e: averagechangel Procedure: coaverag 
>v averagechangelimit.def 
>+10 
>b 8 
Overall breakpoints state: ACTIVE 
Added: 
2: count: 1 Active coaverage::changeLimit(const CoInPIntLong &, const Col 


nPFloat &): 9: if (newLimit<hiLim) 
eA | 


ia Y 


Figure I-2. Setting break point in command operation 


= IMS Object Type Builder 2 
1 7/ Calculate the mean value. Handle the optional connection correc 
2 
2 int count = 3; 
2 value = float(obj1) + float((obi2 + (obi3))); 

oe 2 4f CoptObj1){ value = value + (+—9SR0—EHD countt++; } 
2 if CoptObj2){ value value + C*optObj2); count++; } 
2 a£ (optObj3){ value = value + (*optObj3); count++; } 
eA value = value / count; 
2 
2 #/ Check for alarm limit transgressions or for returning from such 
2 f/f transgressions. Generates events when going into or leaving ala 
3 

> 3 if (value < loLim) { 
3 af C!STATUS[1oLimError]){ 
* STATUS[1oLimError] = gcTrue; /*generate alarm on*/ 
3 sendEventData.valueFloat = value; 
3 sendEventData.eventReason = DCX_ALARM_ON; 
3 sendEventData.eventAttribute = DCK_ELO_LIM1; 
3 sendEvent(); /#* raise events #*/ 
3 eventLoLim ();5 
3 eventAnyLim (); 
4 t 
4 } 
4 else if (STATUS[1loLimError]) { 
A STATUS[1LoLimError] = 3 /*penerate alarm of f4/ 


agenormalt Procedure: hiddenNormal Imp 
at Ox0003458¢ 


>p (float) *value.valueP 
7.5 


>p (float) *obj1.valueP 
10 


>p (float) *optObij1—>valueP 
20 
>i 


Figure I-3. Displaying attribute and connection values 
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